SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/u_man/cat1/perlfunc.Z/perlfunc

Text File | 1998-10-28 | 217.0 KB | 6,403 lines

     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



     NNNNAAAAMMMMEEEE
      perlfunc - Perl builtin functions

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      The functions    in this    section    can serve as terms in an
      expression.  They fall into two major    categories: list
      operators and    named unary operators.    These differ in    their
      precedence relationship with a following comma.  (See    the
      precedence table in the _p_e_r_l_o_p manpage.)  List operators
      take more than one argument, while unary operators can never
      take more than one argument.    Thus, a    comma terminates the
      argument of a    unary operator,    but merely separates the
      arguments of a list operator.     A unary operator generally
      provides a scalar context to its argument, while a list
      operator may provide either scalar and list contexts for its
      arguments.  If it does both, the scalar arguments will be
      first, and the list argument will follow.  (Note that    there
      can ever be only one list argument.)    For instance, _s_p_l_i_c_e()
      has three scalar arguments followed by a list.

      In the syntax    descriptions that follow, list operators that
      expect a list    (and provide list context for the elements of
      the list) are    shown with LIST    as an argument.     Such a    list
      may consist of any combination of scalar arguments or    list
      values; the list values will be included in the list as if
      each individual element were interpolated at that point in
      the list, forming a longer single-dimensional    list value.
      Elements of the LIST should be separated by commas.

      Any function in the list below may be    used either with or
      without parentheses around its arguments.  (The syntax
      descriptions omit the    parentheses.)  If you use the
      parentheses, the simple (but occasionally surprising)    rule
      is this: It _L_O_O_K_S like a function, therefore it _I_S a
      function, and    precedence doesn't matter.  Otherwise it's a
      list operator    or unary operator, and precedence does matter.
      And whitespace between the function and left parenthesis
      doesn't count--so you    need to    be careful sometimes:

          print 1+2+4;      # Prints 7.
          print(1+2) + 4;      # Prints 3.
          print (1+2)+4;      # Also prints    3!
          print +(1+2)+4;      # Prints 7.
          print ((1+2)+4);      # Prints 7.

      If you run Perl with the ----wwww switch it    can warn you about
      this.     For example, the third    line above produces:

          print (...) interpreted as function at - line 1.
          Useless use of integer addition in void context at - line    1.

      For functions    that can be used in either a scalar or list



     Page 1                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      context, nonabortive failure is generally indicated in a
      scalar context by returning the undefined value, and in a
      list context by returning the    null list.

      Remember the following important rule: There is nnnnoooo rrrruuuulllleeee that
      relates the behavior of an expression    in list    context    to its
      behavior in scalar context, or vice versa.  It might do two
      totally different things.  Each operator and function
      decides which    sort of    value it would be most appropriate to
      return in a scalar context.  Some operators return the
      length of the    list that would    have been returned in list
      context.  Some operators return the first value in the list.
      Some operators return    the last value in the list.  Some
      operators return a count of successful operations.  In
      general, they    do what    you want, unless you want consistency.

      An named array in scalar context is quite different from
      what would at    first glance appear to be a list in scalar
      context.  You    can't get a list like (1,2,3) into being in
      scalar context, because the compiler knows the context at
      compile time.     It would generate the scalar comma operator
      there, not the list construction version of the comma.  That
      means    it was never a list to start with.

      In general, functions    in Perl    that serve as wrappers for
      system calls of the same name    (like _c_h_o_w_n(2),    _f_o_r_k(2),
      _c_l_o_s_e_d_i_r(2), etc.) all return    true when they succeed and
      undef    otherwise, as is usually mentioned in the descriptions
      below.  This is different from the C interfaces, which
      return -1 on failure.     Exceptions to this rule are wait(),
      waitpid(), and syscall().  System calls also set the special
      $!  variable on failure.  Other functions do not, except
      accidentally.

      PPPPeeeerrrrllll FFFFuuuunnnnccccttttiiiioooonnnnssss bbbbyyyy CCCCaaaatttteeeeggggoooorrrryyyy

      Here are Perl's functions (including things that look    like
      functions, like some keywords    and named operators) arranged
      by category.    Some functions appear in more than one place.

      Functions for    SCALARs    or strings
           chomp, chop, chr, crypt,    hex, index, lc,    lcfirst,
           length, oct, ord, pack, q/STRING/, qq/STRING/, reverse,
           rindex, sprintf,    substr,    tr///, uc, ucfirst, y///

      Regular expressions and pattern matching
           m//, pos, quotemeta, s///, split, study,    qr//

      Numeric functions
           abs, atan2, cos,    exp, hex, int, log, oct, rand, sin,
           sqrt, srand




     Page 2                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      Functions for    real @ARRAYs
           pop, push, shift, splice, unshift

      Functions for    list data
           grep, join, map,    qw/STRING/, reverse, sort, unpack

      Functions for    real %HASHes
           delete, each, exists, keys, values

      Input    and output functions
           binmode,    close, closedir, dbmclose, dbmopen, die, eof,
           fileno, flock, format, getc, print, printf, read,
           readdir,    rewinddir, seek, seekdir, select, syscall,
           sysread,    sysseek, syswrite, tell, telldir, truncate,
           warn, write

      Functions for    fixed length data or records
           pack, read, syscall, sysread, syswrite, unpack, vec

      Functions for    filehandles, files, or directories
           -_X, chdir, chmod, chown,    chroot,    fcntl, glob, ioctl,
           link, lstat, mkdir, open, opendir, readlink, rename,
           rmdir, stat, symlink, umask, unlink, utime

      Keywords related to the control flow of your perl program
           caller, continue, die, do, dump,    eval, exit, goto,
           last, next, redo, return, sub, wantarray

      Keywords related to scoping
           caller, import, local, my, package, use

      Miscellaneous    functions
           defined,    dump, eval, formline, local, my, reset,
           scalar, undef, wantarray

      Functions for    processes and process groups
           alarm, exec, fork, getpgrp, getppid, getpriority, kill,
           pipe, qx/STRING/, setpgrp, setpriority, sleep, system,
           times, wait, waitpid

      Keywords related to perl modules
           do, import, no, package,    require, use

      Keywords related to classes and object-orientedness
           bless, dbmclose,    dbmopen, package, ref, tie, tied,
           untie, use

      Low-level socket functions
           accept, bind, connect, getpeername, getsockname,
           getsockopt, listen, recv, send, setsockopt, shutdown,
           socket, socketpair




     Page 3                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      System V interprocess    communication functions
           msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop,
           shmctl, shmget, shmread,    shmwrite

      Fetching user    and group info
           endgrent, endhostent, endnetent,    endpwent, getgrent,
           getgrgid, getgrnam, getlogin, getpwent, getpwnam,
           getpwuid, setgrent, setpwent

      Fetching network info
           endprotoent, endservent,    gethostbyaddr, gethostbyname,
           gethostent, getnetbyaddr, getnetbyname, getnetent,
           getprotobyname, getprotobynumber, getprotoent,
           getservbyname, getservbyport, getservent, sethostent,
           setnetent, setprotoent, setservent

      Time-related functions
           gmtime, localtime, time,    times

      Functions new    in perl5
           abs, bless, chomp, chr, exists, formline, glob, import,
           lc, lcfirst, map, my, no, prototype, qx,    qw, readline,
           readpipe, ref, sub*, sysopen, tie, tied,    uc, ucfirst,
           untie, use

           * - sub was a keyword in    perl4, but in perl5 it is an
           operator, which can be used in expressions.

      Functions obsoleted in perl5
           dbmclose, dbmopen

      AAAAllllpppphhhhaaaabbbbeeeettttiiiiccccaaaallll LLLLiiiissssttttiiiinnnngggg ooooffff PPPPeeeerrrrllll FFFFuuuunnnnccccttttiiiioooonnnnssss

      -_X FILEHANDLE

      -_X EXPR

      -_X      A file test, where X is one of the letters listed
          below.  This unary operator takes one    argument,
          either a filename or a filehandle, and tests the
          associated file to see if something is true about
          it.  If the argument is omitted, tests $_, except
          for -t, which    tests STDIN.  Unless otherwise
          documented, it returns 1 for TRUE and    '' for FALSE,
          or the undefined value if the    file doesn't exist.
          Despite the funny names, precedence is the same as
          any other named unary    operator, and the argument may
          be parenthesized like    any other unary    operator.  The
          operator may be any of:






     Page 4                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              -r  File is readable by effective    uid/gid.
              -w  File is writable by effective    uid/gid.
              -x  File is executable by    effective uid/gid.
              -o  File is owned    by effective uid.

              -R  File is readable by real uid/gid.
              -W  File is writable by real uid/gid.
              -X  File is executable by    real uid/gid.
              -O  File is owned    by real    uid.

              -e  File exists.
              -z  File has zero    size.
              -s  File has nonzero size    (returns size).

              -f  File is a plain file.
              -d  File is a directory.
              -l  File is a symbolic link.
              -p  File is a named pipe (FIFO), or Filehandle is    a pipe.
              -S  File is a socket.
              -b  File is a block special file.
              -c  File is a character special file.
              -t  Filehandle is    opened to a tty.

              -u  File has setuid bit set.
              -g  File has setgid bit set.
              -k  File has sticky bit set.

              -T  File is a text file.
              -B  File is a binary file    (opposite of -T).

              -M  Age of file in days when script started.
              -A  Same for access time.
              -C  Same for inode change    time.

          The interpretation of    the file permission operators
          -r, -R, -w, -W, -x, and -X is    based solely on    the
          mode of the file and the uids    and gids of the    user.
          There    may be other reasons you can't actually    read,
          write, or execute the    file, such as AFS access
          control lists.  Also note that, for the superuser,
          -r, -R, -w, and -W always return 1, and -x and -X
          return 1 if any execute bit is set in    the mode.
          Scripts run by the superuser may thus    need to    do a
          stat() to determine the actual mode of the file, or
          temporarily set the uid to something else.

          Example:








     Page 5                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              while (<>) {
              chop;
              next unless -f $_;      # ignore specials
              #...
              }

          Note that -s/a/b/ does not do    a negated
          substitution.     Saying    -exp($foo) still works as
          expected, however--only single letters following a
          minus    are interpreted    as file    tests.

          The -T and -B    switches work as follows.  The first
          block    or so of the file is examined for odd
          characters such as strange control codes or
          characters with the high bit set.  If    too many
          strange characters (>30%) are    found, it's a -B file,
          otherwise it's a -T file.  Also, any file containing
          null in the first block is considered    a binary file.
          If -T    or -B is used on a filehandle, the current
          stdio    buffer is examined rather than the first
          block.  Both -T and -B return    TRUE on    a null file,
          or a file at EOF when    testing    a filehandle.  Because
          you have to read a file to do    the -T test, on    most
          occasions you    want to    use a -f against the file
          first, as in next unless -f $file && -T $file.

          If any of the    file tests (or either the stat() or
          lstat() operators) are given the special filehandle
          consisting of    a solitary underline, then the stat
          structure of the previous file test (or stat
          operator) is used, saving a system call.  (This
          doesn't work with -t,    and you    need to    remember that
          _l_s_t_a_t() and -l will leave values in the stat
          structure for    the symbolic link, not the real    file.)
          Example:

              print "Can do.\n"    if -r $a || -w _ || -x _;

              stat($filename);
              print "Readable\n" if -r _;
              print "Writable\n" if -w _;
              print "Executable\n" if -x _;
              print "Setuid\n" if -u _;
              print "Setgid\n" if -g _;
              print "Sticky\n" if -k _;
              print "Text\n" if    -T _;
              print "Binary\n" if -B _;


      abs VALUE





     Page 6                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      abs      Returns the absolute value of    its argument.  If
          VALUE    is omitted, uses $_.

      accept NEWSOCKET,GENERICSOCKET
          Accepts an incoming socket connect, just as the
          _a_c_c_e_p_t(2) system call    does.  Returns the packed
          address if it    succeeded, FALSE otherwise.  See
          example in the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r
          _C_o_m_m_u_n_i_c_a_t_i_o_n    in the _p_e_r_l_i_p_c manpage.

      alarm    SECONDS

      alarm      Arranges to have a SIGALRM delivered to this process
          after    the specified number of    seconds    have elapsed.
          If SECONDS is    not specified, the value stored    in $_
          is used. (On some machines, unfortunately, the
          elapsed time may be up to one    second less than you
          specified because of how seconds are counted.)  Only
          one timer may    be counting at once.  Each call
          disables the previous    timer, and an argument of 0
          may be supplied to cancel the    previous timer without
          starting a new one.  The returned value is the
          amount of time remaining on the previous timer.

          For delays of    finer granularity than one second, you
          may use Perl's syscall() interface to    access
          _s_e_t_i_t_i_m_e_r(2) if your system supports it, or else see
          the select() entry elsewhere in this document.  It
          is usually a mistake to intermix alarm() and sleep()
          calls.

          If you want to use alarm() to    time out a system call
          you need to use an eval()/die() pair.     You can't
          rely on the alarm causing the    system call to fail
          with $! set to EINTR because Perl sets up signal
          handlers to restart system calls on some systems.
          Using    eval()/die() always works, modulo the caveats
          given    in the section on _S_i_g_n_a_l_s in the _p_e_r_l_i_p_c
          manpage.
















     Page 7                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              eval {
              local    $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
              alarm    $timeout;
              $nread = sysread SOCKET, $buffer, $size;
              alarm    0;
              };
              if ($@) {
              die unless $@    eq "alarm\n";    # propagate unexpected errors
              # timed out
              }
              else {
              # didn't
              }


      atan2    Y,X
          Returns the arctangent of Y/X    in the range -pi to
          pi.

          For the tangent operation, you may use the
          POSIX::tan() function, or use    the familiar relation:

              sub tan {    sin($_[0]) / cos($_[0])     }


      bind SOCKET,NAME
          Binds    a network address to a socket, just as the
          bind system call does.  Returns TRUE if it
          succeeded, FALSE otherwise.  NAME should be a    packed
          address of the appropriate type for the socket.  See
          the examples in the section on _S_o_c_k_e_t_s:
          _C_l_i_e_n_t/_S_e_r_v_e_r    _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage.

      binmode FILEHANDLE
          Arranges for the file    to be read or written in
          "binary" mode    in operating systems that distinguish
          between binary and text files.  Files    that are not
          in binary mode have CR LF sequences translated to LF
          on input and LF translated to    CR LF on output.
          Binmode has no effect    under Unix; in MS-DOS and
          similarly archaic systems, it    may be imperative--
          otherwise your MS-DOS-damaged    C library may mangle
          your file.  The key distinction between systems that
          need binmode() and those that    don't is their text
          file formats.     Systems like Unix, MacOS, and Plan9
          that delimit lines with a single character, and that
          encode that character    in C as    "\n", do not need
          binmode().  The rest need it.     If FILEHANDLE is an
          expression, the value    is taken as the    name of    the
          filehandle.





     Page 8                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      bless    REF,CLASSNAME

      bless    REF
          This function    tells the thingy referenced by REF
          that it is now an object in the CLASSNAME package--
          or the current package if no CLASSNAME is specified,
          which    is often the case.  It returns the reference
          for convenience, because a bless() is    often the last
          thing    in a constructor.  Always use the two-argument
          version if the function doing    the blessing might be
          inherited by a derived class.     See the _p_e_r_l_t_o_o_t
          manpage and the _p_e_r_l_o_b_j manpage for more about the
          blessing (and    blessings) of objects.

      caller EXPR

      caller  Returns the context of the current subroutine    call.
          In scalar context, returns the caller's package name
          if there is a    caller,    that is, if we're in a
          subroutine or    eval() or require(), and the undefined
          value    otherwise.  In list context, returns

              ($package, $filename, $line) = caller;

          With EXPR, it    returns    some extra information that
          the debugger uses to print a stack trace.  The value
          of EXPR indicates how    many call frames to go back
          before the current one.

              ($package, $filename, $line, $subroutine,
               $hasargs, $wantarray, $evaltext,    $is_require) = caller($i);

          Here $subroutine may be "(eval)" if the frame    is not
          a subroutine call, but an eval().  In    such a case
          additional elements $evaltext    and $is_require    are
          set: $is_require is true if the frame    is created by
          a require or use statement, $evaltext    contains the
          text of the eval EXPR    statement.  In particular, for
          a eval BLOCK statement, $filename is "(eval)", but
          $evaltext is undefined.  (Note also that each    use
          statement creates a require frame inside an eval
          EXPR)    frame.

          Furthermore, when called from    within the DB package,
          caller returns more detailed information: it sets
          the list variable @DB::args to be the    arguments with
          which    the subroutine was invoked.

          Be aware that    the optimizer might have optimized
          call frames away before caller() had a chance    to get
          the information. That    means that caller(N) might not
          return information about the call frame you expect



     Page 9                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          it do, for N > 1. In particular, @DB::args might
          have information from    the previous time caller() was
          called.

      chdir    EXPR
          Changes the working directory    to EXPR, if possible.
          If EXPR is omitted, changes to home directory.
          Returns TRUE upon success, FALSE otherwise.  See
          example under    die().

      chmod    LIST
          Changes the permissions of a list of files.  The
          first    element    of the list must be the    numerical
          mode,    which should probably be an octal number, and
          which    definitely should _n_o_t a    string of octal
          digits:  0644    is okay, '0644'    is not.     Returns the
          number of files successfully changed.     See also the
          oct entry elsewhere in this documentif all you have
          is a string.

              $cnt = chmod 0755, 'foo',    'bar';
              chmod 0755, @executables;
              $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
                                   # --w----r-T
              $mode = '0644'; chmod oct($mode),    'foo'; # this is better
              $mode = 0644;   chmod $mode, 'foo';      # this is best


      chomp    VARIABLE

      chomp    LIST

      chomp      This is a slightly safer version of the chop entry
          elsewhere in this document.  It removes any line
          ending that corresponds to the current value of $/
          (also    known as $INPUT_RECORD_SEPARATOR in the
          English module).  It returns the total number    of
          characters removed from all its arguments.  It's
          often    used to    remove the newline from    the end    of an
          input    record when you're worried that    the final
          record may be    missing    its newline.  When in
          paragraph mode ($/ = ""), it removes all trailing
          newlines from    the string.  If    VARIABLE is omitted,
          it chomps $_.     Example:

              while (<>) {
              chomp;  # avoid \n on    last field
              @array = split(/:/);
              # ...
              }

          You can actually chomp anything that's an lvalue,



     Page 10                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          including an assignment:

              chomp($cwd = `pwd`);
              chomp($answer = <STDIN>);

          If you chomp a list, each element is chomped,    and
          the total number of characters removed is returned.

      chop VARIABLE

      chop LIST

      chop      Chops    off the    last character of a string and returns
          the character    chopped.  It's used primarily to
          remove the newline from the end of an    input record,
          but is much more efficient than s/\n// because it
          neither scans    nor copies the string.    If VARIABLE is
          omitted, chops $_.  Example:

              while (<>) {
              chop;      # avoid \n on    last field
              @array = split(/:/);
              #...
              }

          You can actually chop    anything that's    an lvalue,
          including an assignment:

              chop($cwd    = `pwd`);
              chop($answer = <STDIN>);

          If you chop a    list, each element is chopped.    Only
          the value of the last    chop() is returned.

          Note that chop() returns the last character.    To
          return all but the last character, use
          substr($string, 0, -1).

      chown    LIST
          Changes the owner (and group)    of a list of files.
          The first two    elements of the    list must be the
          _N_U_M_E_R_I_C_A_L uid    and gid, in that order.     Returns the
          number of files successfully changed.

              $cnt = chown $uid, $gid, 'foo', 'bar';
              chown $uid, $gid,    @filenames;

          Here's an example that looks up nonnumeric uids in
          the passwd file:






     Page 11                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              print "User: ";
              chop($user = <STDIN>);
              print "Files: ";
              chop($pattern = <STDIN>);

              ($login,$pass,$uid,$gid) = getpwnam($user)
              or die "$user    not in passwd file";

              @ary = glob($pattern);      # expand filenames
              chown $uid, $gid,    @ary;

          On most systems, you are not allowed to change the
          ownership of the file    unless you're the superuser,
          although you should be able to change    the group to
          any of your secondary    groups.     On insecure systems,
          these    restrictions may be relaxed, but this is not a
          portable assumption.

      chr NUMBER

      chr      Returns the character    represented by that NUMBER in
          the character    set.  For example, chr(65) is "A" in
          ASCII.  For the reverse, use the ord entry elsewhere
          in this document.

          If NUMBER is omitted,    uses $_.

      chroot FILENAME

      chroot  This function    works like the system call by the same
          name:    it makes the named directory the new root
          directory for    all further pathnames that begin with
          a "/"    by your    process    and all    its children.  (It
          doesn't change your current working directory, which
          is unaffected.)  For security    reasons, this call is
          restricted to    the superuser.    If FILENAME is
          omitted, does    a chroot() to $_.

      close    FILEHANDLE

      close      Closes the file or pipe associated with the file
          handle, returning TRUE only if stdio successfully
          flushes buffers and closes the system    file
          descriptor. Closes the currently selected filehandle
          if the argument is omitted.

          You don't have to close FILEHANDLE if    you are
          immediately going to do another open() on it,
          because open() will close it for you.     (See open().)
          However, an explicit close() on an input file    resets
          the line counter ($.), while the implicit close done
          by open() does not.



     Page 12                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          If the file handle came from a piped open close()
          will additionally return FALSE if one    of the other
          system calls involved    fails or if the    program    exits
          with non-zero    status.     (If the only problem was that
          the program exited non-zero $! will be set to    0.)
          Also,    closing    a pipe waits for the process executing
          on the pipe to complete, in case you want to look at
          the output of    the pipe afterwards.  Closing a    pipe
          explicitly also puts the exit    status value of    the
          command into $?.

          Example:

              open(OUTPUT, '|sort >foo')  # pipe to sort
              or die "Can't    start sort: $!";
              #...              # print stuff    to output
              close OUTPUT          # wait for sort to finish
              or warn $! ? "Error closing sort pipe: $!"
                     : "Exit status $? from sort";
              open(INPUT, 'foo')      # get    sort's results
              or die "Can't    open 'foo' for input: $!";

          FILEHANDLE may be an expression whose    value can be
          used as an indirect filehandle, usually the real
          filehandle name.

      closedir DIRHANDLE
          Closes a directory opened by opendir() and returns
          the success of that system call.

          DIRHANDLE may    be an expression whose value can be
          used as an indirect dirhandle, usually the real
          dirhandle name.

      connect SOCKET,NAME
          Attempts to connect to a remote socket, just as the
          connect system call does.  Returns TRUE if it
          succeeded, FALSE otherwise.  NAME should be a    packed
          address of the appropriate type for the socket.  See
          the examples in the section on _S_o_c_k_e_t_s:
          _C_l_i_e_n_t/_S_e_r_v_e_r    _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage.

      continue BLOCK
          Actually a flow control statement rather than    a
          function.  If    there is a continue BLOCK attached to
          a BLOCK (typically in    a while    or foreach), it    is
          always executed just before the conditional is about
          to be    evaluated again, just like the third part of a
          for loop in C.  Thus it can be used to increment a
          loop variable, even when the loop has    been continued
          via the next statement (which    is similar to the C
          continue statement).



     Page 13                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          last,    next, or redo may appear within    a continue
          block. last and redo will behave as if they had been
          executed within the main block. So will next,    but
          since    it will    execute    a continue block, it may be
          more entertaining.

              while (EXPR) {
              ### redo always comes    here
              do_something;
              }    continue {
              ### next always comes    here
              do_something_else;
              # then back the top to re-check EXPR
              }
              ### last always comes here

          Omitting the continue    section    is semantically
          equivalent to    using an empty one, logically enough.
          In that case,    next goes directly back    to check the
          condition at the top of the loop.

      cos EXPR
          Returns the cosine of    EXPR (expressed    in radians).
          If EXPR is omitted, takes cosine of $_.

          For the inverse cosine operation, you    may use    the
          POSIX::acos()    function, or use this relation:

              sub acos { atan2(    sqrt(1 - $_[0] * $_[0]), $_[0] ) }


      crypt    PLAINTEXT,SALT
          Encrypts a string exactly like the _c_r_y_p_t(3) function
          in the C library (assuming that you actually have a
          version there    that has not been extirpated as    a
          potential munition).    This can prove useful for
          checking the password    file for lousy passwords,
          amongst other    things.     Only the guys wearing white
          hats should do this.

          Note that crypt() is intended    to be a    one-way
          function, much like breaking eggs to make an
          omelette.  There is no (known) corresponding decrypt
          function.  As    a result, this function    isn't all that
          useful for cryptography.  (For that, see your    nearby
          CPAN mirror.)

          Here's an example that makes sure that whoever runs
          this program knows their own password:

              $pwd = (getpwuid($<))[1];
              $salt = substr($pwd, 0, 2);



     Page 14                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              system "stty -echo";
              print "Password: ";
              chop($word = <STDIN>);
              print "\n";
              system "stty echo";

              if (crypt($word, $salt) ne $pwd) {
              die "Sorry...\n";
              }    else {
              print    "ok\n";
              }

          Of course, typing in your own    password to whoever
          asks you for it is unwise.

      dbmclose HASH
          [This    function has been superseded by    the untie()
          function.]

          Breaks the binding between a DBM file    and a hash.

      dbmopen HASH,DBNAME,MODE
          [This    function has been superseded by    the tie()
          function.]

          This binds a _d_b_m(3), _n_d_b_m(3),    _s_d_b_m(3), _g_d_b_m(3), or
          Berkeley DB file to a    hash.  HASH is the name    of the
          hash.     (Unlike normal    open(),    the first argument is
          _N_O_T a    filehandle, even though    it looks like one).
          DBNAME is the    name of    the database (without the ._d_i_r
          or ._p_a_g extension if any).  If the database does not
          exist, it is created with protection specified by
          MODE (as modified by the umask()).  If your system
          supports only    the older DBM functions, you may
          perform only one dbmopen() in    your program.  In
          older    versions of Perl, if your system had neither
          DBM nor ndbm,    calling    dbmopen() produced a fatal
          error; it now    falls back to _s_d_b_m(3).

          If you don't have write access to the    DBM file, you
          can only read    hash variables,    not set    them.  If you
          want to test whether you can write, either use file
          tests    or try setting a dummy hash entry inside an
          eval(), which    will trap the error.

          Note that functions such as keys() and values() may
          return huge lists when used on large DBM files.  You
          may prefer to    use the    each() function    to iterate
          over large DBM files.     Example:






     Page 15                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              #    print out history file offsets
              dbmopen(%HIST,'/usr/lib/news/history',0666);
              while (($key,$val) = each    %HIST) {
              print    $key, '    = ', unpack('L',$val), "\n";
              }
              dbmclose(%HIST);

          See also the _A_n_y_D_B_M__F_i_l_e manpage for a more general
          description of the pros and cons of the various dbm
          approaches, as well as the _D_B__F_i_l_e manpage for a
          particularly rich implementation.

      defined EXPR

      defined Returns a Boolean value telling whether EXPR has a
          value    other than the undefined value undef.  If EXPR
          is not present, $_ will be checked.

          Many operations return undef to indicate failure,
          end of file, system error, uninitialized variable,
          and other exceptional    conditions.  This function
          allows you to    distinguish undef from other values.
          (A simple Boolean test will not distinguish among
          undef, zero, the empty string, and "0", which    are
          all equally false.)  Note that since undef is    a
          valid    scalar,    its presence doesn't _n_e_c_e_s_s_a_r_i_l_y
          indicate an exceptional condition: pop() returns
          undef    when its argument is an    empty array, _o_r    when
          the element to return    happens    to be undef.

          You may also use defined() to    check whether a
          subroutine exists, by    saying defined &func without
          parentheses.    On the other hand, use of defined()
          upon aggregates (hashes and arrays) is not
          guaranteed to    produce    intuitive results, and should
          probably be avoided.

          When used on a hash element, it tells    you whether
          the value is defined,    not whether the    key exists in
          the hash.  Use the exists entry elsewhere in this
          documentfor the latter purpose.

          Examples:

              print if defined $switch{'D'};
              print "$val\n" while defined($val    = pop(@ary));
              die "Can't readlink $sym:    $!"
              unless defined($value    = readlink $sym);
              sub foo {    defined    &$bar ?    &$bar(@_) : die    "No bar"; }
              $debugging = 0 unless defined $debugging;

          Note:     Many folks tend to overuse defined(), and



     Page 16                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          then are surprised to    discover that the number 0 and
          "" (the zero-length string) are, in fact, defined
          values.  For example,    if you say

              "ab" =~ /a(.*)b/;

          The pattern match succeeds, and $1 is    defined,
          despite the fact that    it matched "nothing".  But it
          didn't really    match nothing--rather, it matched
          something that happened to be    0 characters long.
          This is all very above-board and honest.  When a
          function returns an undefined    value, it's an
          admission that it couldn't give you an honest
          answer.  So you should use defined() only when
          you're questioning the integrity of what you're
          trying to do.     At other times, a simple comparison
          to 0 or "" is    what you want.

          Currently, using defined() on    an entire array    or
          hash reports whether memory for that aggregate has
          ever been allocated.    So an array you    set to the
          empty    list appears undefined initially, and one that
          once was full    and that you then set to the empty
          list still appears defined.  You should instead use
          a simple test    for size:

              if (@an_array) { print "has array    elements\n" }
              if (%a_hash)   { print "has hash members\n"   }

          Using    undef()    on these, however, does    clear their
          memory and then report them as not defined anymore,
          but you shouldn't do that unless you don't plan to
          use them again, because it saves time    when you load
          them up again    to have    memory already ready to    be
          filled.  The normal way to free up space used    by an
          aggregate is to assign the empty list.

          This counterintuitive    behavior of defined() on
          aggregates may be changed, fixed, or broken in a
          future release of Perl.

          See also the undef, exists,  and ref entries
          elsewhere in this document.

      delete EXPR
          Deletes the specified    _k_e_y(s) and their associated
          values from a    hash.  For each    key, returns the
          deleted value    associated with    that key, or the
          undefined value if there was no such key.  Deleting
          from $ENV{} modifies the environment.     Deleting from
          a hash tied to a DBM file deletes the    entry from the
          DBM file.  (But deleting from    a tie()d hash doesn't



     Page 17                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          necessarily return anything.)

          The following    deletes    all the    values of a hash:

              foreach $key (keys %HASH)    {
              delete $HASH{$key};
              }

          And so does this:

              delete @HASH{keys    %HASH}

          (But both of these are slower    than just assigning
          the empty list, or using undef().)  Note that    the
          EXPR can be arbitrarily complicated as long as the
          final    operation is a hash element lookup or hash
          slice:

              delete $ref->[$x][$y]{$key};
              delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};


      die LIST
          Outside an eval(), prints the    value of LIST to
          STDERR and exits with    the current value of $!
          (errno).  If $! is 0,    exits with the value of    ($? >>
          8) (backtick `command` status).  If ($? >> 8)    is 0,
          exits    with 255.  Inside an eval(), the error message
          is stuffed into $@ and the eval() is terminated with
          the undefined    value.    This makes die() the way to
          raise    an exception.

          Equivalent examples:

              die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
              chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"

          If the value of EXPR does not    end in a newline, the
          current script line number and input line number (if
          any) are also    printed, and a newline is supplied.
          Hint:    sometimes appending ", stopped"    to your
          message will cause it    to make    better sense when the
          string "at foo line 123" is appended.     Suppose you
          are running script "canasta".

              die "/etc/games is no good";
              die "/etc/games is no good, stopped";

          produce, respectively

              /etc/games is no good at canasta line 123.
              /etc/games is no good, stopped at    canasta    line 123.



     Page 18                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          See also exit() and warn().

          If LIST is empty and $@ already contains a value
          (typically from a previous eval) that    value is
          reused after appending "\t...propagated".  This is
          useful for propagating exceptions:

              eval { ... };
              die unless $@ =~ /Expected exception/;

          If $@    is empty then the string "Died"    is used.

          You can arrange for a    callback to be run just    before
          the die() does its deed, by setting the
          $SIG{__DIE__}    hook.  The associated handler will be
          called with the error    text and can change the    error
          message, if it sees fit, by calling die() again.
          See the section on $_S_I_G{_e_x_p_r}    in the _p_e_r_l_v_a_r manpage
          for details on setting %SIG entries, and the section
          on _e_v_a_l _B_L_O_C_K    for some examples.

          Note that the    $SIG{__DIE__} hook is called even
          inside _e_v_a_l()ed blocks/strings.  If one wants    the
          hook to do nothing in    such situations, put

              die @_ if $^S;

          as the first line of the handler (see    the section on
          $^_S in the _p_e_r_l_v_a_r manpage).

      do BLOCK
          Not really a function.  Returns the value of the
          last command in the sequence of commands indicated
          by BLOCK.  When modified by a    loop modifier,
          executes the BLOCK once before testing the loop
          condition.  (On other    statements the loop modifiers
          test the conditional first.)

      do SUBROUTINE(LIST)
          A deprecated form of subroutine call.     See the
          _p_e_r_l_s_u_b manpage.

      do EXPR Uses the value of EXPR as a filename and executes
          the contents of the file as a    Perl script.  Its
          primary use is to include subroutines    from a Perl
          subroutine library.

              do 'stat.pl';

          is just like

              scalar eval `cat stat.pl`;



     Page 19                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          except that it's more    efficient and concise, keeps
          track    of the current filename    for error messages,
          and searches all the ----IIII libraries if the file    isn't
          in the current directory (see    also the @INC array in
          the section on _P_r_e_d_e_f_i_n_e_d _N_a_m_e_s in the _p_e_r_l_v_a_r
          manpage).  It    is also    different in how code
          evaluated with do FILENAME doesn't see lexicals in
          the enclosing    scope like eval    STRING does.  It's the
          same,    however, in that it does reparse the file
          every    time you call it, so you probably don't    want
          to do    this inside a loop.

          If do    cannot read the    file, it returns undef and
          sets $! to the error.       If do can read the file but
          cannot compile it, it    returns    undef and sets an
          error    message    in $@.     If the    file is    successfully
          compiled, do returns the value of the    last
          expression evaluated.

          Note that inclusion of library modules is better
          done with the    use() and require() operators, which
          also do automatic error checking and raise an
          exception if there's a problem.

          You might like to use    do to read in a    program
          configuration    file.  Manual error checking can be
          done this way:

              #    read in    config files: system first, then user
              for $file    ("/share/prog/defaults.rc",
                 "$ENV{HOME}/.someprogrc") {
              unless ($return = do $file) {
                  warn "couldn't parse $file: $@" if $@;
                  warn "couldn't do    $file: $!"    unless defined $return;
                  warn "couldn't run $file"          unless $return;
              }
              }


      dump LABEL
          This causes an immediate core    dump.  Primarily this
          is so    that you can use the uuuunnnndddduuuummmmpppp program to turn
          your core dump into an executable binary after
          having initialized all your variables    at the
          beginning of the program.  When the new binary is
          executed it will begin by executing a    goto LABEL
          (with    all the    restrictions that goto suffers).
          Think    of it as a goto    with an    intervening core dump
          and reincarnation.  If LABEL is omitted, restarts
          the program from the top.  WARNING: Any files    opened
          at the time of the dump will NOT be open any more
          when the program is reincarnated, with possible



     Page 20                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          resulting confusion on the part of Perl.  See    also
          ----uuuu option in the _p_e_r_l_r_u_n manpage.

          Example:

              #!/usr/bin/perl
              require 'getopt.pl';
              require 'stat.pl';
              %days = (
              'Sun'    => 1,
              'Mon'    => 2,
              'Tue'    => 3,
              'Wed'    => 4,
              'Thu'    => 5,
              'Fri'    => 6,
              'Sat'    => 7,
              );

              dump QUICKSTART if $ARGV[0] eq '-d';

              QUICKSTART:
              Getopt('f');

          This operator    is largely obsolete, partly because
          it's very hard to convert a core file    into an
          executable, and because the real perl-to-C compiler
          has superseded it.

      each HASH
          When called in list context, returns a 2-element
          list consisting of the key and value for the next
          element of a hash, so    that you can iterate over it.
          When called in scalar    context, returns the key for
          only the "next" element in the hash.    (Note: Keys
          may be "0" or    "", which are logically    false; you may
          wish to avoid    constructs like    while ($k = each %foo)
          {} for this reason.)

          Entries are returned in an apparently    random order.
          When the hash    is entirely read, a null array is
          returned in list context (which when assigned
          produces a FALSE (0) value), and undef in scalar
          context.  The    next call to each() after that will
          start    iterating again.  There    is a single iterator
          for each hash, shared    by all each(), keys(), and
          values() function calls in the program; it can be
          reset    by reading all the elements from the hash, or
          by evaluating    keys HASH or values HASH.  If you add
          or delete elements of    a hash while you're iterating
          over it, you may get entries skipped or duplicated,
          so don't.




     Page 21                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          The following    prints out your    environment like the
          _p_r_i_n_t_e_n_v(1) program, only in a different order:

              while (($key,$value) = each %ENV)    {
              print    "$key=$value\n";
              }

          See also keys() and values().

      eof FILEHANDLE

      eof ()

      eof      Returns 1 if the next    read on    FILEHANDLE will    return
          end of file, or if FILEHANDLE    is not open.
          FILEHANDLE may be an expression whose    value gives
          the real filehandle.    (Note that this    function
          actually reads a character and then ungetc()s    it, so
          isn't    very useful in an interactive context.)     Do
          not read from    a terminal file    (or call
          eof(FILEHANDLE) on it) after end-of-file is reached.
          Filetypes such as terminals may lose the end-of-file
          condition if you do.

          An eof without an argument uses the last file    read
          as argument.    Using eof() with empty parentheses is
          very different.  It indicates    the pseudo file    formed
          of the files listed on the command line, i.e., eof()
          is reasonable    to use inside a    while (<>) loop    to
          detect the end of only the last file.     Use eof(ARGV)
          or eof without the parentheses to test _E_A_C_H file in
          a while (<>) loop.  Examples:

              #    reset line numbering on    each input file
              while (<>) {
              next if /^\s*#/;      # skip comments
              print    "$.\t$_";
              }    continue {
              close    ARGV  if eof;      # Not    eof()!
              }

              #    insert dashes just before last line of last file
              while (<>) {
              if (eof()) {          # check for end of current file
                  print "--------------\n";
                  close(ARGV);      # close or break; is needed if we
                          # are    reading    from the terminal
              }
              print;
              }

          Practical hint: you almost never need    to use eof in



     Page 22                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          Perl,    because    the input operators return false
          values when they run out of data, or if there    was an
          error.

      eval EXPR

      eval BLOCK
          In the first form, the return    value of EXPR is
          parsed and executed as if it were a little Perl
          program.  The    value of the expression    (which is
          itself determined within scalar context) is first
          parsed, and if there weren't any errors, executed in
          the context of the current Perl program, so that any
          variable settings or subroutine and format
          definitions remain afterwards.  Note that the    value
          is parsed every time the eval    executes.  If EXPR is
          omitted, evaluates $_.  This form is typically used
          to delay parsing and subsequent execution of the
          text of EXPR until run time.

          In the second    form, the code within the BLOCK    is
          parsed only once--at the same    time the code
          surrounding the eval itself was parsed--and executed
          within the context of    the current Perl program.
          This form is typically used to trap exceptions more
          efficiently than the first (see below), while    also
          providing the    benefit    of checking the    code within
          BLOCK    at compile time.

          The final semicolon, if any, may be omitted from the
          value    of EXPR    or within the BLOCK.

          In both forms, the value returned is the value of
          the last expression evaluated    inside the mini-
          program; a return statement may be also used,    just
          as with subroutines.    The expression providing the
          return value is evaluated in void, scalar, or    list
          context, depending on    the context of the eval
          itself.  See the wantarray entry elsewhere in    this
          documentfor more on how the evaluation context can
          be determined.

          If there is a    syntax error or    runtime    error, or a
          die()    statement is executed, an undefined value is
          returned by eval(), and $@ is    set to the error
          message.  If there was no error, $@ is guaranteed to
          be a null string.  Beware that using eval() neither
          silences perl    from printing warnings to STDERR, nor
          does it stuff    the text of warning messages into $@.
          To do    either of those, you have to use the
          $SIG{__WARN__} facility.  See    the warn entry
          elsewhere in this document and the _p_e_r_l_v_a_r manpage.



     Page 23                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          Note that, because eval() traps otherwise-fatal
          errors, it is    useful for determining whether a
          particular feature (such as socket() or symlink())
          is implemented.  It is also Perl's exception
          trapping mechanism, where the    die operator is    used
          to raise exceptions.

          If the code to be executed doesn't vary, you may use
          the eval-BLOCK form to trap run-time errors without
          incurring the    penalty    of recompiling each time.  The
          error, if any, is still returned in $@.  Examples:

              #    make divide-by-zero nonfatal
              eval { $answer = $a / $b;    }; warn    $@ if $@;

              #    same thing, but    less efficient
              eval '$answer = $a / $b';    warn $@    if $@;

              #    a compile-time error
              eval { $answer = };          # WRONG

              #    a run-time error
              eval '$answer =';      # sets $@

          When using the eval{}    form as    an exception trap in
          libraries, you may wish not to trigger any __DIE__
          hooks    that user code may have    installed.  You    can
          use the local    $SIG{__DIE__} construct    for this
          purpose, as shown in this example:

              #    a very private exception trap for divide-by-zero
              eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
              warn $@ if $@;

          This is especially significant, given    that __DIE__
          hooks    can call die() again, which has    the effect of
          changing their error messages:

              #    __DIE__    hooks may modify error messages
              {
             local $SIG{'__DIE__'} =
                sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
             eval {    die "foo lives here" };
             print $@ if $@;        # prints "bar lives here"
              }

          With an eval(), you should be    especially careful to
          remember what's being    looked at when:

              eval $x;          # CASE 1
              eval "$x";      # CASE 2




     Page 24                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              eval '$x';      # CASE 3
              eval { $x    };      # CASE 4

              eval "\$$x++";      # CASE 5
              $$x++;          # CASE 6

          Cases    1 and 2    above behave identically: they run the
          code contained in the    variable $x.  (Although    case 2
          has misleading double    quotes making the reader
          wonder what else might be happening (nothing is).)
          Cases    3 and 4    likewise behave    in the same way: they
          run the code '$x', which does    nothing    but return the
          value    of $x.    (Case 4    is preferred for purely    visual
          reasons, but it also has the advantage of compiling
          at compile-time instead of at    run-time.)  Case 5 is
          a place where    normally you _W_O_U_L_D like    to use double
          quotes, except that in this particular situation,
          you can just use symbolic references instead,    as in
          case 6.

      exec LIST

      exec PROGRAM LIST
          The exec() function executes a system    command    _A_N_D
          _N_E_V_E_R    _R_E_T_U_R_N_S    - use system() instead of exec() if
          you want it to return. It fails and returns FALSE
          only if the command does not exist _a_n_d it is
          executed directly instead of via your    system's
          command shell    (see below).

          Since    it's a common mistake to use exec() instead of
          system(), Perl warns you if there is a following
          statement which isn't    die(), warn(), or exit() (if
          -w is    set  -    but you    always do that).   If you
          _r_e_a_l_l_y want to follow    an exec() with some other
          statement, you can use one of    these styles to    avoid
          the warning:

              exec ('foo')   or    print STDERR "couldn't exec foo: $!";
              {    exec ('foo') };    print STDERR "couldn't exec foo: $!";

          If there is more than    one argument in    LIST, or if
          LIST is an array with    more than one value, calls
          _e_x_e_c_v_p(3) with the arguments in LIST.     If there is
          only one scalar argument or an array with one
          element in it, the argument is checked for shell
          metacharacters, and if there are any,    the entire
          argument is passed to    the system's command shell for
          parsing (this    is /bin/sh -c on Unix platforms, but
          varies on other platforms).  If there    are no shell
          metacharacters in the    argument, it is    split into
          words    and passed directly to execvp(), which is more



     Page 25                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          efficient.  Note:  exec() and    system() do not    flush
          your output buffer, so you may need to set $|    to
          avoid    lost output.  Examples:

              exec '/bin/echo',    'Your arguments    are: ',    @ARGV;
              exec "sort $outfile | uniq";

          If you don't really want to execute the first
          argument, but    want to    lie to the program you are
          executing about its own name,    you can    specify    the
          program you actually want to run as an "indirect
          object" (without a comma) in front of    the LIST.
          (This    always forces interpretation of    the LIST as a
          multivalued list, even if there is only a single
          scalar in the    list.)    Example:

              $shell = '/bin/csh';
              exec $shell '-sh';      # pretend it's a login shell

          or, more directly,

              exec {'/bin/csh'}    '-sh';      # pretend it's a login shell

          When the arguments get executed via the system
          shell, results will be subject to its    quirks and
          capabilities.     See the section on `_S_T_R_I_N_G` in    the
          _p_e_r_l_o_p manpage for details.

          Using    an indirect object with    exec() or system() is
          also more secure.  This usage    forces interpretation
          of the arguments as a    multivalued list, even if the
          list had just    one argument.  That way    you're safe
          from the shell expanding wildcards or    splitting up
          words    with whitespace    in them.

              @args = (    "echo surprise"    );

              system @args;          # subject to shell escapes
                          # if @args ==    1
              system { $args[0]    } @args;  # safe even with one-arg list

          The first version, the one without the indirect
          object, ran the _e_c_h_o program,    passing    it "surprise"
          an argument.    The second version didn't--it tried to
          run a    program    literally called "_e_c_h_o _s_u_r_p_r_i_s_e",
          didn't find it, and set $? to    a non-zero value
          indicating failure.

          Note that exec() will    not call your END blocks, nor
          will it call any DESTROY methods in your objects.





     Page 26                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      exists EXPR
          Returns TRUE if the specified    hash key exists    in its
          hash array, even if the corresponding    value is
          undefined.

              print "Exists\n" if exists $array{$key};
              print "Defined\n"    if defined $array{$key};
              print "True\n" if    $array{$key};

          A hash element can be    TRUE only if it's defined, and
          defined if it    exists,    but the    reverse    doesn't
          necessarily hold true.

          Note that the    EXPR can be arbitrarily    complicated as
          long as the final operation is a hash    key lookup:

              if (exists $ref->{"A"}{"B"}{$key}) { ... }

          Although the last element will not spring into
          existence just because its existence was tested,
          intervening ones will.  Thus $ref->{"A"} $ref->{"B"}
          will spring into existence due to the    existence test
          for a    $key element.  This autovivification may be
          fixed    in a later release.

      exit EXPR
          Evaluates EXPR and exits immediately with that
          value.  (Actually, it    calls any defined END routines
          first, but the END routines may not abort the    exit.
          Likewise any object destructors that need to be
          called are called before exit.)  Example:

              $ans = <STDIN>;
              exit 0 if    $ans =~    /^[Xx]/;

          See also die().  If EXPR is omitted, exits with 0
          status.  The only universally    portable values    for
          EXPR are 0 for success and 1 for error; all other
          values are subject to    unpredictable interpretation
          depending on the environment in which    the Perl
          program is running.

          You shouldn't    use exit() to abort a subroutine if
          there's any chance that someone might    want to    trap
          whatever error happened.  Use    die() instead, which
          can be trapped by an eval().

          All END{} blocks are run at exit time.  See the
          _p_e_r_l_s_u_b manpage for details.

      exp EXPR




     Page 27                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      exp      Returns _e (the natural logarithm base) to the    power
          of EXPR.  If EXPR is omitted,    gives exp($_).

      fcntl    FILEHANDLE,FUNCTION,SCALAR
          Implements the _f_c_n_t_l(2) function.  You'll probably
          have to say

              use Fcntl;

          first    to get the correct constant definitions.
          Argument processing and value    return works just like
          ioctl() below. For example:

              use Fcntl;
              fcntl($filehandle, F_GETFL, $packed_return_buffer)
              or die "can't    fcntl F_GETFL: $!";

          You don't have to check for defined()    on the return
          from fnctl().     Like ioctl(), it maps a 0 return from
          the system call into "0 but true" in Perl.  This
          string is true in boolean context and    0 in numeric
          context.  It is also exempt from the normal ----wwww
          warnings on improper numeric conversions.

          Note that fcntl() will produce a fatal error if used
          on a machine that doesn't implement _f_c_n_t_l(2).

      fileno FILEHANDLE
          Returns the file descriptor for a filehandle.     This
          is useful for    constructing bitmaps for select() and
          low-level POSIX tty-handling operations.  If
          FILEHANDLE is    an expression, the value is taken as
          an indirect filehandle, generally its    name.

          You can use this to find out whether two handles
          refer    to the same underlying descriptor:

              if (fileno(THIS) == fileno(THAT))    {
              print    "THIS and THAT are dups\n";
              }


      flock    FILEHANDLE,OPERATION
          Calls    _f_l_o_c_k(2), or an    emulation of it, on
          FILEHANDLE.  Returns TRUE for    success, FALSE on
          failure.  Produces a fatal error if used on a
          machine that doesn't implement _f_l_o_c_k(2), _f_c_n_t_l(2)
          locking, or _l_o_c_k_f(3).     flock() is Perl's portable
          file locking interface, although it locks only
          entire files,    not records.

          On many platforms (including most versions or    clones



     Page 28                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          of Unix), locks established by flock() are mmmmeeeerrrreeeellllyyyy
          aaaaddddvvvviiiissssoooorrrryyyy.  Such discretionary    locks are more
          flexible, but    offer fewer guarantees.     This means
          that files locked with flock() may be    modified by
          programs that    do not also use    flock().  Windows NT
          and OS/2 are among the platforms which enforce
          mandatory locking.  See your local documentation for
          details.

          OPERATION is one of LOCK_SH, LOCK_EX,    or LOCK_UN,
          possibly combined with LOCK_NB.  These constants are
          traditionally    valued 1, 2, 8 and 4, but you can use
          the symbolic names if    import them from the Fcntl
          module, either individually, or as a group using the
          ':flock' tag.     LOCK_SH requests a shared lock,
          LOCK_EX requests an exclusive    lock, and LOCK_UN
          releases a previously    requested lock.     If LOCK_NB is
          added    to LOCK_SH or LOCK_EX then flock() will    return
          immediately rather than blocking waiting for the
          lock (check the return status    to see if you got it).

          To avoid the possibility of mis-coordination,    Perl
          flushes FILEHANDLE before (un)locking    it.

          Note that the    emulation built    with _l_o_c_k_f(3) doesn't
          provide shared locks,    and it requires    that
          FILEHANDLE be    open with write    intent.     These are the
          semantics that _l_o_c_k_f(3) implements.  Most (all?)
          systems implement _l_o_c_k_f(3) in    terms of _f_c_n_t_l(2)
          locking, though, so the differing semantics
          shouldn't bite too many people.

          Note also that some versions of flock() cannot lock
          things over the network; you would need to use the
          more system-specific fcntl() for that.  If you like
          you can force    Perl to    ignore your system's _f_l_o_c_k(2)
          function, and    so provide its own _f_c_n_t_l(2)-based
          emulation, by    passing    the switch -Ud_flock to    the
          _C_o_n_f_i_g_u_r_e program when you configure perl.

          Here's a mailbox appender for    BSD systems.

              use Fcntl    ':flock'; # import LOCK_* constants

              sub lock {
              flock(MBOX,LOCK_EX);
              # and, in case someone appended
              # while we were waiting...
              seek(MBOX, 0,    2);
              }





     Page 29                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              sub unlock {
              flock(MBOX,LOCK_UN);
              }

              open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
                  or die "Can't open mailbox: $!";

              lock();
              print MBOX $msg,"\n\n";
              unlock();

          See also the _D_B__F_i_l_e manpage for other _f_l_o_c_k()
          examples.

      fork      Does a _f_o_r_k(2) system    call.  Returns the child pid
          to the parent    process, 0 to the child    process, or
          undef    if the fork is unsuccessful.

          Note:    unflushed buffers remain unflushed in both
          processes, which means you may need to set $|
          ($AUTOFLUSH in English) or call the autoflush()
          method of IO::Handle to avoid    duplicate output.

          If you fork()    without    ever waiting on    your children,
          you will accumulate zombies:

              $SIG{CHLD} = sub { wait };

          There's also the double-fork trick (error checking
          on fork() returns omitted);

              unless ($pid = fork) {
              unless (fork)    {
                  exec "what you really wanna do";
                  die "no exec";
                  #    ... or ...
                  ## (some_perl_code_here)
                  exit 0;
              }
              exit 0;
              }
              waitpid($pid,0);

          See also the _p_e_r_l_i_p_c manpage for more    examples of
          forking and reaping moribund children.

          Note that if your forked child inherits system file
          descriptors like STDIN and STDOUT that are actually
          connected by a pipe or socket, even if you exit,
          then the remote server (such as, say,    httpd or rsh)
          won't    think you're done.  You    should reopen those to
          /_d_e_v/_n_u_l_l if it's any    issue.



     Page 30                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      format  Declare a picture format for use by the write()
          function.  For example:

              format Something =
              Test:    @<<<<<<<< @||||| @>>>>>
                $str,      $%,     '$' . int($num)
              .

              $str = "widget";
              $num = $cost/$quantity;
              $~ = 'Something';
              write;

          See the _p_e_r_l_f_o_r_m manpage for many details and
          examples.

      formline PICTURE,LIST
          This is an internal function used by formats,    though
          you may call it, too.     It formats (see the _p_e_r_l_f_o_r_m
          manpage) a list of values according to the contents
          of PICTURE, placing the output into the format
          output accumulator, $^A (or $ACCUMULATOR in
          English).  Eventually, when a    write()    is done, the
          contents of $^A are written to some filehandle, but
          you could also read $^A yourself and then set    $^A
          back to "".  Note that a format typically does one
          formline() per line of form, but the formline()
          function itself doesn't care how many    newlines are
          embedded in the PICTURE.  This means that the    ~ and
          ~~ tokens will treat the entire PICTURE as a single
          line.     You may therefore need    to use multiple
          formlines to implement a single record format, just
          like the format compiler.

          Be careful if    you put    double quotes around the
          picture, because an "@" character may    be taken to
          mean the beginning of    an array name.    formline()
          always returns TRUE.    See the    _p_e_r_l_f_o_r_m manpage for
          other    examples.

      getc FILEHANDLE

      getc      Returns the next character from the input file
          attached to FILEHANDLE, or the undefined value at
          end of file, or if there was an error.  If
          FILEHANDLE is    omitted, reads from STDIN.  This is
          not particularly efficient.  It cannot be used to
          get unbuffered single-characters, however.  For
          that,    try something more like:






     Page 31                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              if ($BSD_STYLE) {
              system "stty cbreak </dev/tty    >/dev/tty 2>&1";
              }
              else {
              system "stty", '-icanon', 'eol', "\001";
              }

              $key = getc(STDIN);

              if ($BSD_STYLE) {
              system "stty -cbreak </dev/tty >/dev/tty 2>&1";
              }
              else {
              system "stty", 'icanon', 'eol', '^@';    # ASCII    null
              }
              print "\n";

          Determination    of whether $BSD_STYLE should be    set is
          left as an exercise to the reader.

          The POSIX::getattr() function    can do this more
          portably on systems purporting POSIX compliance.
          See also the Term::ReadKey module from your nearest
          CPAN site; details on    CPAN can be found on the CPAN
          entry    in the _p_e_r_l_m_o_d manpage.

      getlogin
          Implements the C library function of the same    name,
          which    on most    systems    returns    the current login from
          /_e_t_c/_u_t_m_p, if    any.  If null, use getpwuid().

              $login = getlogin    || getpwuid($<)    || "Kilroy";

          Do not consider getlogin() for authentication: it is
          not as secure    as getpwuid().

      getpeername SOCKET
          Returns the packed sockaddr address of other end of
          the SOCKET connection.

              use Socket;
              $hersockaddr    =    getpeername(SOCK);
              ($port, $iaddr) =    unpack_sockaddr_in($hersockaddr);
              $herhostname    =    gethostbyaddr($iaddr, AF_INET);
              $herstraddr     =    inet_ntoa($iaddr);


      getpgrp PID
          Returns the current process group for    the specified
          PID.    Use a PID of 0 to get the current process
          group    for the    current    process.  Will raise an
          exception if used on a machine that doesn't



     Page 32                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          implement _g_e_t_p_g_r_p(2).     If PID    is omitted, returns
          process group    of current process.  Note that the
          POSIX    version    of getpgrp() does not accept a PID
          argument, so only PID==0 is truly portable.

      getppid Returns the process id of the    parent process.

      getpriority WHICH,WHO
          Returns the current priority for a process, a
          process group, or a user.  (See the _g_e_t_p_r_i_o_r_i_t_y(_2)
          manpage.)  Will raise    a fatal    exception if used on a
          machine that doesn't implement _g_e_t_p_r_i_o_r_i_t_y(2).

      getpwnam NAME

      getgrnam NAME

      gethostbyname    NAME

      getnetbyname NAME

      getprotobyname NAME

      getpwuid UID

      getgrgid GID

      getservbyname    NAME,PROTO

      gethostbyaddr    ADDR,ADDRTYPE

      getnetbyaddr ADDR,ADDRTYPE

      getprotobynumber NUMBER

      getservbyport    PORT,PROTO

      getpwent

      getgrent

      gethostent

      getnetent

      getprotoent

      getservent

      setpwent





     Page 33                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      setgrent

      sethostent STAYOPEN

      setnetent STAYOPEN

      setprotoent STAYOPEN

      setservent STAYOPEN

      endpwent

      endgrent

      endhostent

      endnetent

      endprotoent

      endservent
          These    routines perform the same functions as their
          counterparts in the system library.  In list
          context, the return values from the various get
          routines are as follows:

              ($name,$passwd,$uid,$gid,
             $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
              ($name,$passwd,$gid,$members) = getgr*
              ($name,$aliases,$addrtype,$length,@addrs)    = gethost*
              ($name,$aliases,$addrtype,$net) =    getnet*
              ($name,$aliases,$proto) =    getproto*
              ($name,$aliases,$port,$proto) = getserv*

          (If the entry    doesn't    exist you get a    null list.)

          In scalar context, you get the name, unless the
          function was a lookup    by name, in which case you get
          the other thing, whatever it is.  (If    the entry
          doesn't exist    you get    the undefined value.)  For
          example:

              $uid   = getpwnam($name);
              $name  = getpwuid($num);
              $name  = getpwent();
              $gid   = getgrnam($name);
              $name  = getgrgid($num;
              $name  = getgrent();
              #etc.

          In _g_e_t_p_w*() the fields $quota, $comment, and $expire
          are special cases in the sense that in many systems



     Page 34                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          they are unsupported.     If the    $quota is unsupported,
          it is    an empty scalar.  If it    is supported, it
          usually encodes the disk quota.  If the $comment
          field    is unsupported,    it is an empty scalar.    If it
          is supported it usually encodes some administrative
          comment about    the user.  In some systems the $quota
          field    may be $change or $age,    fields that have to do
          with password    aging.    In some    systems    the $comment
          field    may be $class.    The $expire field, if present,
          encodes the expiration period    of the account or the
          password.  For the availability and the exact
          meaning of these fields in your system, please
          consult your _g_e_t_p_w_n_a_m(3) documentation and your
          _p_w_d._h    file.  You can also find out from within Perl
          which    meaning    your $quota and    $comment fields    have
          and whether you have the $expire field by using the
          Config module    and the    values d_pwquota, d_pwage,
          d_pwchange, d_pwcomment, and d_pwexpire.

          The $members value returned by _g_e_t_g_r*() is a space
          separated list of the    login names of the members of
          the group.

          For the _g_e_t_h_o_s_t*() functions,    if the h_errno
          variable is supported    in C, it will be returned to
          you via $? if    the function call fails.  The @addrs
          value    returned by a successful call is a list    of the
          raw addresses    returned by the    corresponding system
          library call.     In the    Internet domain, each address
          is four bytes    long and you can unpack    it by saying
          something like:

              ($a,$b,$c,$d) = unpack('C4',$addr[0]);

          If you get tired of remembering which    element    of the
          return list contains which return value, by-name
          interfaces are also provided in modules:
          File::stat, Net::hostent, Net::netent,
          Net::protoent, Net::servent, Time::gmtime,
          Time::localtime, and User::grent.  These override
          the normal built-in, replacing them with versions
          that return objects with the appropriate names for
          each field.  For example:

             use File::stat;
             use User::pwent;
             $is_his = (stat($filename)->uid ==    pwent($whoever)->uid);

          Even though it looks like they're the    same method
          calls    (uid), they aren't, because a File::stat
          object is different from a User::pwent object.




     Page 35                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      getsockname SOCKET
          Returns the packed sockaddr address of this end of
          the SOCKET connection.

              use Socket;
              $mysockaddr = getsockname(SOCK);
              ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);


      getsockopt SOCKET,LEVEL,OPTNAME
          Returns the socket option requested, or undef    if
          there    is an error.

      glob EXPR

      glob      Returns the value of EXPR with filename expansions
          such as the standard Unix shell /_b_i_n/_s_h would    do.
          This is the internal function    implementing the <*.c>
          operator, but    you can    use it directly.  If EXPR is
          omitted, $_ is used.    The <*.c> operator is
          discussed in more detail in the section on _I/_O
          _O_p_e_r_a_t_o_r_s in the _p_e_r_l_o_p manpage.

      gmtime EXPR
          Converts a time as returned by the time function to
          a 9-element array with the time localized for    the
          standard Greenwich time zone.     Typically used    as
          follows:

              #     0    1       2     3     4    5      6    7     8
              ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                  gmtime(time);

          All array elements are numeric, and come straight
          out of a struct tm.  In particular this means    that
          $mon has the range 0..11 and $wday has the range
          0..6 with sunday as day 0.  Also, $year is the
          number of years since    1900, that is, $year is    123 in
          year 2023, _n_o_t simply    the last two digits of the
          year.

          If EXPR is omitted, does gmtime(time()).

          In scalar context, returns the _c_t_i_m_e(3) value:

              $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"

          Also see the timegm()    function provided by the
          Time::Local module, and the _s_t_r_f_t_i_m_e(3) function
          available via    the POSIX module.

          This scalar value is nnnnooootttt locale dependent, see the



     Page 36                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          _p_e_r_l_l_o_c_a_l_e manpage, but instead a Perl builtin.
          Also see the Time::Local module, and the _s_t_r_f_t_i_m_e(3)
          and _m_k_t_i_m_e(3)    function available via the POSIX
          module.  To get somewhat similar but locale
          dependent date strings, set up your locale
          environment variables    appropriately (please see the
          _p_e_r_l_l_o_c_a_l_e manpage) and try for example:

              use POSIX    qw(strftime);
              $now_string =    strftime "%a %b    %e %H:%M:%S %Y", gmtime;

          Note that the    %a and %b, the short forms of the day
          of the week and the month of the year, may not
          necessarily be three characters wide.

      goto LABEL

      goto EXPR

      goto &NAME
          The goto-LABEL form finds the    statement labeled with
          LABEL    and resumes execution there.  It may not be
          used to go into any construct    that requires
          initialization, such as a subroutine or a foreach
          loop.     It also can't be used to go into a construct
          that is optimized away, or to    get out    of a block or
          subroutine given to sort().  It can be used to go
          almost anywhere else within the dynamic scope,
          including out    of subroutines,    but it's usually
          better to use    some other construct such as last or
          die().  The author of    Perl has never felt the    need
          to use this form of goto (in Perl, that is--C    is
          another matter).

          The goto-EXPR    form expects a label name, whose scope
          will be resolved dynamically.     This allows for
          computed gotos per FORTRAN, but isn't    necessarily
          recommended if you're    optimizing for
          maintainability:

              goto ("FOO", "BAR", "GLARCH")[$i];

          The goto-&NAME form is highly    magical, and
          substitutes a    call to    the named subroutine for the
          currently running subroutine.     This is used by
          AUTOLOAD subroutines that wish to load another
          subroutine and then pretend that the other
          subroutine had been called in    the first place
          (except that any modifications to @_ in the current
          subroutine are propagated to the other subroutine.)
          After    the goto, not even caller() will be able to
          tell that this routine was called first.



     Page 37                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      grep BLOCK LIST

      grep EXPR,LIST
          This is similar in spirit to,    but not    the same as,
          _g_r_e_p(1) and its relatives.  In particular, it    is not
          limited to using regular expressions.

          Evaluates the    BLOCK or EXPR for each element of LIST
          (locally setting $_ to each element) and returns the
          list value consisting    of those elements for which
          the expression evaluated to TRUE.  In    a scalar
          context, returns the number of times the expression
          was TRUE.

              @foo = grep(!/^#/, @bar);       # weed out comments

          or equivalently,

              @foo = grep {!/^#/} @bar;       # weed out comments

          Note that, because $_    is a reference into the    list
          value, it can    be used    to modify the elements of the
          array.  While    this is    useful and supported, it can
          cause    bizarre    results    if the LIST is not a named
          array.  Similarly, grep returns aliases into the
          original list, much like the way that    a for loop's
          index    variable aliases the list elements.  That is,
          modifying an element of a list returned by grep (for
          example, in a    foreach, map() or another grep())
          actually modifies the    element    in the original    list.

          See also the map entry elsewhere in this documentfor
          an array composed of the results of the BLOCK    or
          EXPR.

      hex EXPR

      hex      Interprets EXPR as a hex string and returns the
          corresponding    value.    (To convert strings that might
          start    with either 0 or 0x see    the oct    entry
          elsewhere in this document.)    If EXPR    is omitted,
          uses $_.

              print hex    '0xAf';    # prints '175'
              print hex    'aF';    # same


      import  There    is no builtin import() function.  It is    just
          an ordinary method (subroutine) defined (or
          inherited) by    modules    that wish to export names to
          another module.  The use() function calls the
          import() method for the package used.     See also the



     Page 38                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          use()    entry elsewhere    in this    documentthe _p_e_r_l_m_o_d
          manpage, and the _E_x_p_o_r_t_e_r manpage.

      index    STR,SUBSTR,POSITION

      index    STR,SUBSTR
          Returns the position of the first occurrence of
          SUBSTR in STR    at or after POSITION.  If POSITION is
          omitted, starts searching from the beginning of the
          string.  The return value is based at    0 (or whatever
          you've set the $[ variable to--but don't do that).
          If the substring is not found, returns one less than
          the base, ordinarily -1.

      int EXPR

      int      Returns the integer portion of EXPR.    If EXPR    is
          omitted, uses    $_.  You should    not use    this for
          rounding, because it truncates towards 0, and
          because machine representations of floating point
          numbers can sometimes    produce    counterintuitive
          results.  Usually sprintf() or printf(), or the
          POSIX::floor or POSIX::ceil functions, would serve
          you better.

      ioctl    FILEHANDLE,FUNCTION,SCALAR
          Implements the _i_o_c_t_l(2) function.  You'll probably
          have to say

              require "ioctl.ph"; # probably in    /usr/local/lib/perl/ioctl.ph

          first    to get the correct function definitions.  If
          _i_o_c_t_l._p_h doesn't exist or doesn't have the correct
          definitions you'll have to roll your own, based on
          your C header    files such as <_s_y_s/_i_o_c_t_l._h>.  (There
          is a Perl script called hhhh2222pppphhhh that comes with the
          Perl kit that    may help you in    this, but it's
          nontrivial.)    SCALAR will be read and/or written
          depending on the FUNCTION--a pointer to the string
          value    of SCALAR will be passed as the    third argument
          of the actual    ioctl()    call.  (If SCALAR has no
          string value but does    have a numeric value, that
          value    will be    passed rather than a pointer to    the
          string value.     To guarantee this to be TRUE, add a 0
          to the scalar    before using it.)  The pack() and
          unpack() functions are useful    for manipulating the
          values of structures used by ioctl().     The following
          example sets the erase character to DEL.







     Page 39                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              require 'ioctl.ph';
              $getp = &TIOCGETP;
              die "NO TIOCGETP"    if $@ || !$getp;
              $sgttyb_t    = "ccccs";          # 4 chars and    a short
              if (ioctl(STDIN,$getp,$sgttyb)) {
              @ary = unpack($sgttyb_t,$sgttyb);
              $ary[2] = 127;
              $sgttyb = pack($sgttyb_t,@ary);
              ioctl(STDIN,&TIOCSETP,$sgttyb)
                  || die "Can't ioctl: $!";
              }

          The return value of ioctl() (and fcntl()) is as
          follows:

              if OS    returns:      then Perl returns:
                  -1            undefined value
                   0          string "0 but    true"
              anything else              that number

          Thus Perl returns TRUE on success and    FALSE on
          failure, yet you can still easily determine the
          actual value returned    by the operating system:

              ($retval = ioctl(...)) ||    ($retval = -1);
              printf "System returned %d\n", $retval;

          The special string "0    but true" is excempt from ----wwww
          complaints about improper numeric conversions.

      join EXPR,LIST
          Joins    the separate strings of    LIST into a single
          string with fields separated by the value of EXPR,
          and returns the string.  Example:

              $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);

          See the split    entry elsewhere    in this    document.

      keys HASH
          Returns a list consisting of all the keys of the
          named    hash.  (In a scalar context, returns the
          number of keys.)  The    keys are returned in an
          apparently random order, but it is the same order as
          either the values() or each()    function produces
          (given that the hash has not been modified).    As a
          side effect, it resets HASH's    iterator.

          Here is yet another way to print your    environment:






     Page 40                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              @keys = keys %ENV;
              @values =    values %ENV;
              while ($#keys >= 0) {
              print    pop(@keys), '=', pop(@values), "\n";
              }

          or how about sorted by key:

              foreach $key (sort(keys %ENV)) {
              print    $key, '=', $ENV{$key}, "\n";
              }

          To sort an array by value, you'll need to use    a
          sort() function.  Here's a descending    numeric    sort
          of a hash by its values:

              foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
              printf "%4d %s\n", $hash{$key}, $key;
              }

          As an    lvalue keys() allows you to increase the
          number of hash buckets allocated for the given hash.
          This can gain    you a measure of efficiency if you
          know the hash    is going to get    big.  (This is similar
          to pre-extending an array by assigning a larger
          number to $#array.)  If you say

              keys %hash = 200;

          then %hash will have at least    200 buckets allocated
          for it--256 of them, in fact,    since it rounds    up to
          the next power of two.  These    buckets    will be
          retained even    if you do %hash    = (), use undef    %hash
          if you want to free the storage while    %hash is still
          in scope.  You can't shrink the number of buckets
          allocated for    the hash using keys() in this way (but
          you needn't worry about doing    this by    accident, as
          trying has no    effect).

      kill LIST
          Sends    a signal to a list of processes.  The first
          element of the list must be the signal to send.
          Returns the number of    processes successfully
          signaled.

              $cnt = kill 1, $child1, $child2;
              kill 9, @goners;

          Unlike in the    shell, in Perl if the _S_I_G_N_A_L is
          negative, it kills process groups instead of
          processes.  (On System V, a negative _P_R_O_C_E_S_S number
          will also kill process groups, but that's not



     Page 41                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          portable.)  That means you usually want to use
          positive not negative    signals.  You may also use a
          signal name in quotes.  See the section on _S_i_g_n_a_l_s
          in the _p_e_r_l_i_p_c manpage for details.

      last LABEL

      last      The last command is like the break statement in C
          (as used in loops); it immediately exits the loop in
          question.  If    the LABEL is omitted, the command
          refers to the    innermost enclosing loop.  The
          continue block, if any, is not executed:

              LINE: while (<STDIN>) {
              last LINE if /^$/;      # exit when done with    header
              #...
              }

          See also the continue    entry elsewhere    in this
          documentfor an illustration of how last, next, and
          redo work.

      lc EXPR

      lc      Returns an lowercased    version    of EXPR.  This is the
          internal function implementing the \L    escape in
          double-quoted    strings.  Respects current LC_CTYPE
          locale if use    locale in force.  See the _p_e_r_l_l_o_c_a_l_e
          manpage.

          If EXPR is omitted, uses $_.

      lcfirst EXPR

      lcfirst Returns the value of EXPR with the first character
          lowercased.  This is the internal function
          implementing the \l escape in    double-quoted strings.
          Respects current LC_CTYPE locale if use locale in
          force.  See the _p_e_r_l_l_o_c_a_l_e manpage.

          If EXPR is omitted, uses $_.

      length EXPR

      length  Returns the length in    bytes of the value of EXPR.
          If EXPR is omitted, returns length of    $_.

      link OLDFILE,NEWFILE
          Creates a new    filename linked    to the old filename.
          Returns TRUE for success, FALSE otherwise.





     Page 42                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      listen SOCKET,QUEUESIZE
          Does the same    thing that the listen system call
          does.     Returns TRUE if it succeeded, FALSE
          otherwise.  See example in the section on _S_o_c_k_e_t_s:
          _C_l_i_e_n_t/_S_e_r_v_e_r    _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage.

      local    EXPR
          A local modifies the listed variables    to be local to
          the enclosing    block, file, or    eval.  If more than
          one value is listed, the list    must be    placed in
          parentheses.    See the    section    on _T_e_m_p_o_r_a_r_y _V_a_l_u_e_s
          _v_i_a _l_o_c_a_l() in the _p_e_r_l_s_u_b manpage for details,
          including issues with    tied arrays and    hashes.

          You really probably want to be using my() instead,
          because local() isn't    what most people think of as
          "local".  See    the section on _P_r_i_v_a_t_e _V_a_r_i_a_b_l_e_s _v_i_a
          _m_y() in the _p_e_r_l_s_u_b manpage for details.

      localtime EXPR
          Converts a time as returned by the time function to
          a 9-element array with the time analyzed for the
          local    time zone.  Typically used as follows:

              #     0    1       2     3     4    5      6    7     8
              ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                  localtime(time);

          All array elements are numeric, and come straight
          out of a struct tm.  In particular this means    that
          $mon has the range 0..11 and $wday has the range
          0..6 with sunday as day 0.  Also, $year is the
          number of years since    1900, that is, $year is    123 in
          year 2023, and _n_o_t simply the    last two digits    of the
          year.

          If EXPR is omitted, uses the current time
          (localtime(time)).

          In scalar context, returns the _c_t_i_m_e(3) value:

              $now_string = localtime;    # e.g.,    "Thu Oct 13 04:54:34 1994"

          This scalar value is nnnnooootttt locale dependent, see the
          _p_e_r_l_l_o_c_a_l_e manpage, but instead a Perl builtin.
          Also see the Time::Local module, and the _s_t_r_f_t_i_m_e(3)
          and _m_k_t_i_m_e(3)    function available via the POSIX
          module.  To get somewhat similar but locale
          dependent date strings, set up your locale
          environment variables    appropriately (please see the
          _p_e_r_l_l_o_c_a_l_e manpage) and try for example:




     Page 43                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              use POSIX    qw(strftime);
              $now_string =    strftime "%a %b    %e %H:%M:%S %Y", localtime;

          Note that the    %a and %b, the short forms of the day
          of the week and the month of the year, may not
          necessarily be three characters wide.

      log EXPR

      log      Returns the natural logarithm    (base _e) of EXPR.  If
          EXPR is omitted, returns log of $_.

      lstat    FILEHANDLE

      lstat    EXPR

      lstat      Does the same    thing as the stat() function
          (including setting the special _ filehandle) but
          stats    a symbolic link    instead    of the file the
          symbolic link    points to.  If symbolic    links are
          unimplemented    on your    system,    a normal stat()    is
          done.

          If EXPR is omitted, stats $_.

      m//      The match operator.  See the _p_e_r_l_o_p manpage.

      map BLOCK LIST

      map EXPR,LIST
          Evaluates the    BLOCK or EXPR for each element of LIST
          (locally setting $_ to each element) and returns the
          list value composed of the results of    each such
          evaluation.  Evaluates BLOCK or EXPR in a list
          context, so each element of LIST may produce zero,
          one, or more elements    in the returned    value.

              @chars = map(chr,    @nums);

          translates a list of numbers to the corresponding
          characters.  And

              %hash = map { getkey($_) => $_ } @array;

          is just a funny way to write

              %hash = ();
              foreach $_ (@array) {
              $hash{getkey($_)} = $_;
              }

          Note that, because $_    is a reference into the    list



     Page 44                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          value, it can    be used    to modify the elements of the
          array.  While    this is    useful and supported, it can
          cause    bizarre    results    if the LIST is not a named
          array.  See also the grep entry elsewhere in this
          documentfor an array composed    of those items of the
          original list    for which the BLOCK or EXPR evaluates
          to true.

      mkdir    FILENAME,MODE
          Creates the directory    specified by FILENAME, with
          permissions specified    by MODE    (as modified by
          umask).  If it succeeds it returns TRUE, otherwise
          it returns FALSE and sets $! (errno).

      msgctl ID,CMD,ARG
          Calls    the System V IPC function _m_s_g_c_t_l(2).  You'll
          probably have    to say

              use IPC::SysV;

          first    to get the correct constant definitions.  If
          CMD is IPC_STAT, then    ARG must be a variable which
          will hold the    returned msqid_ds structure.  Returns
          like ioctl():    the undefined value for    error, "0 but
          true"    for zero, or the actual    return value
          otherwise.  See also IPC::SysV and
          IPC::Semaphore::Msg documentation.

      msgget KEY,FLAGS
          Calls    the System V IPC function _m_s_g_g_e_t(2).  Returns
          the message queue id,    or the undefined value if
          there    is an error.  See also IPC::SysV and
          IPC::SysV::Msg documentation.

      msgsnd ID,MSG,FLAGS
          Calls    the System V IPC function msgsnd to send the
          message MSG to the message queue ID.    MSG must begin
          with the long    integer    message    type, which may    be
          created with pack("l", $type).  Returns TRUE if
          successful, or FALSE if there    is an error.  See also
          IPC::SysV and    IPC::SysV::Msg documentation.

      msgrcv ID,VAR,SIZE,TYPE,FLAGS
          Calls    the System V IPC function msgrcv to receive a
          message from message queue ID    into variable VAR with
          a maximum message size of SIZE.  Note    that if    a
          message is received, the message type    will be    the
          first    thing in VAR, and the maximum length of    VAR is
          SIZE plus the    size of    the message type.  Returns
          TRUE if successful, or FALSE if there    is an error.
          See also IPC::SysV and IPC::SysV::Msg    documentation.




     Page 45                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      my EXPR A my() declares the listed variables to be local
          (lexically) to the enclosing block, file, or eval().
          If more than one value is listed, the    list must be
          placed in parentheses.  See the section on _P_r_i_v_a_t_e
          _V_a_r_i_a_b_l_e_s _v_i_a    _m_y() in    the _p_e_r_l_s_u_b manpage for
          details.

      next LABEL

      next      The next command is like the continue    statement in
          C; it    starts the next    iteration of the loop:

              LINE: while (<STDIN>) {
              next LINE if /^#/;      # discard comments
              #...
              }

          Note that if there were a continue block on the
          above, it would get executed even on discarded
          lines.  If the LABEL is omitted, the command refers
          to the innermost enclosing loop.

          See also the continue    entry elsewhere    in this
          documentfor an illustration of how last, next, and
          redo work.

      no Module LIST
          See the the use entry    elsewhere in this
          documentfunction, which no is    the opposite of.

      oct EXPR

      oct      Interprets EXPR as an    octal string and returns the
          corresponding    value.    (If EXPR happens to start off
          with 0x, interprets it as a hex string instead.)
          The following    will handle decimal, octal, and    hex in
          the standard Perl or C notation:

              $val = oct($val) if $val =~ /^0/;

          If EXPR is omitted, uses $_.    This function is
          commonly used    when a string such as 644 needs    to be
          converted into a file    mode, for example. (Although
          perl will automatically convert strings into numbers
          as needed, this automatic conversion assumes base
          10.)

      open FILEHANDLE,EXPR

      open FILEHANDLE
          Opens    the file whose filename    is given by EXPR, and
          associates it    with FILEHANDLE.  If FILEHANDLE    is an



     Page 46                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          expression, its value    is used    as the name of the
          real filehandle wanted.  If EXPR is omitted, the
          scalar variable of the same name as the FILEHANDLE
          contains the filename.  (Note    that lexical
          variables--those declared with my()--will not    work
          for this purpose; so if you're using my(), specify
          EXPR in your call to open.)

          If the filename begins with '<' or nothing, the file
          is opened for    input.    If the filename    begins with
          '>', the file    is truncated and opened    for output,
          being    created    if necessary. If the filename begins
          with '>>', the file is opened    for appending, again
          being    created    if necessary. You can put a '+'    in
          front    of the '>' or '<' to indicate that you want
          both read and    write access to    the file; thus '+<' is
          almost always    preferred for read/write updates--the
          '+>' mode would clobber the file first.  You can't
          usually use either read-write    mode for updating
          textfiles, since they    have variable length records.
          See the ----iiii switch in the _p_e_r_l_r_u_n manpage for a
          better approach.

          The prefix and the filename may be separated with
          spaces.  These various prefixes correspond to    the
          _f_o_p_e_n(3) modes of 'r', 'r+', 'w', 'w+', 'a', and
          'a+'.

          If the filename begins with '|', the filename    is
          interpreted as a command to which output is to be
          piped, and if    the filename ends with a '|', the
          filename is interpreted See the section on _U_s_i_n_g
          _o_p_e_n() _f_o_r _I_P_C in the    _p_e_r_l_i_p_c    manpage    for more
          examples of this.  (You are not allowed to open() to
          a command that pipes both in _a_n_d out,    but see    the
          _I_P_C::_O_p_e_n_2 manpage, the _I_P_C::_O_p_e_n_3 manpage, and the
          section on _B_i_d_i_r_e_c_t_i_o_n_a_l _C_o_m_m_u_n_i_c_a_t_i_o_n in the
          _p_e_r_l_i_p_c manpage for alternatives.)

          Opening '-' opens STDIN and opening '>-' opens
          STDOUT.  Open    returns    nonzero    upon success, the
          undefined value otherwise.  If the open() involved a
          pipe,    the return value happens to be the pid of the
          subprocess.

          If you're unfortunate    enough to be running Perl on a
          system that distinguishes between text files and
          binary files (modern operating systems don't care),
          then you should check    out the    binmode    entry
          elsewhere in this documentfor    tips for dealing with
          this.     The key distinction between systems that need
          binmode() and    those that don't is their text file



     Page 47                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          formats.  Systems like Unix, MacOS, and Plan9, which
          delimit lines    with a single character, and which
          encode that character    in C as    "\n", do not need
          binmode().  The rest need it.

          When opening a file, it's usually a bad idea to
          continue normal execution if the request failed, so
          open() is frequently used in connection with die().
          Even if die()    won't do what you want (say, in    a CGI
          script, where    you want to make a nicely formatted
          error    message    (but there are modules that can    help
          with that problem)) you should always    check the
          return value from opening a file. The    infrequent
          exception is when working with an unopened
          filehandle is    actually what you want to do.

          Examples:

              $ARTICLE = 100;
              open ARTICLE or die "Can't find article $ARTICLE:    $!\n";
              while (<ARTICLE>)    {...

              open(LOG,    '>>/usr/spool/news/twitlog'); #    (log is    reserved)
              #    if the open fails, output is discarded

              open(DBASE, '+<dbase.mine')          #    open for update
              or die "Can't    open 'dbase.mine' for update: $!";

              open(ARTICLE, "caesar <$article |")     #    decrypt    article
              or die "Can't    start caesar: $!";

              open(EXTRACT, "|sort >/tmp/Tmp$$")      #    $$ is our process id
              or die "Can't    start sort: $!";

              #    process    argument list of files along with any includes

              foreach $file (@ARGV) {
              process($file, 'fh00');
              }

              sub process {
              my($filename,    $input)    = @_;
              $input++;          # this is a string increment
              unless (open($input, $filename)) {
                  print STDERR "Can't open $filename: $!\n";
                  return;
              }








     Page 48                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              local    $_;
              while    (<$input>) {          # note use of    indirection
                  if (/^#include "(.*)"/) {
                  process($1, $input);
                  next;
                  }
                  #...          # whatever
              }
              }

          You may also,    in the Bourne shell tradition, specify
          an EXPR beginning with '>&', in which    case the rest
          of the string    is interpreted as the name of a
          filehandle (or file descriptor, if numeric) to be
          duped    and opened.  You may use & after >, >>,    <, +>,
          +>>, and +<.    The mode you specify should match the
          mode of the original filehandle.  (Duping a
          filehandle does not take into    account    any existing
          contents of stdio buffers.)  Here is a script    that
          saves, redirects, and    restores STDOUT    and STDERR:

              #!/usr/bin/perl
              open(OLDOUT, ">&STDOUT");
              open(OLDERR, ">&STDERR");

              open(STDOUT, ">foo.out") || die "Can't redirect stdout";
              open(STDERR, ">&STDOUT") || die "Can't dup stdout";

              select(STDERR); $| = 1;      # make unbuffered
              select(STDOUT); $| = 1;      # make unbuffered

              print STDOUT "stdout 1\n";  # this works for
              print STDERR "stderr 1\n";  # subprocesses too

              close(STDOUT);
              close(STDERR);

              open(STDOUT, ">&OLDOUT");
              open(STDERR, ">&OLDERR");

              print STDOUT "stdout 2\n";
              print STDERR "stderr 2\n";

          If you specify '<&=N', where N is a number, then
          Perl will do an equivalent of    C's fdopen() of    that
          file descriptor; this    is more    parsimonious of    file
          descriptors.    For example:

              open(FILEHANDLE, "<&=$fd")

          If you open a    pipe on    the command '-', i.e., either
          '|-' or '-|',    then there is an implicit fork done,



     Page 49                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          and the return value of open is the pid of the child
          within the parent process, and 0 within the child
          process.  (Use defined($pid) to determine whether
          the open was successful.)  The filehandle behaves
          normally for the parent, but i/o to that filehandle
          is piped from/to the STDOUT/STDIN of the child
          process.  In the child process the filehandle    isn't
          opened--i/o happens from/to the new STDOUT or    STDIN.
          Typically this is used like the normal piped open
          when you want    to exercise more control over just how
          the pipe command gets    executed, such as when you are
          running setuid, and don't want to have to scan shell
          commands for metacharacters.    The following pairs
          are more or less equivalent:

              open(FOO,    "|tr '[a-z]' '[A-Z]'");
              open(FOO,    "|-") || exec 'tr', '[a-z]', '[A-Z]';

              open(FOO,    "cat -n    '$file'|");
              open(FOO,    "-|") || exec 'cat', '-n', $file;

          See the section on _S_a_f_e _P_i_p_e _O_p_e_n_s in    the _p_e_r_l_i_p_c
          manpage for more examples of this.

          NOTE:    On any operation that may do a fork, any
          unflushed buffers remain unflushed in    both
          processes, which means you may need to set $|    to
          avoid    duplicate output.

          Closing any piped filehandle causes the parent
          process to wait for the child    to finish, and returns
          the status value in $?.

          The filename passed to open will have    leading    and
          trailing whitespace deleted, and the normal
          redirection characters honored.  This    property,
          known    as "magic open", can often be used to good
          effect.  A user could    specify    a filename of "_r_s_h _c_a_t
          _f_i_l_e |", or you could    change certain filenames as
          needed:

              $filename    =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
              open(FH, $filename) or die "Can't    open $filename:    $!";

          However, to open a file with arbitrary weird
          characters in    it, it's necessary to protect any
          leading and trailing whitespace:

              $file =~ s#^(\s)#./$1#;
              open(FOO,    "< $file\0");

          If you want a    "real" C open()    (see the _o_p_e_n(_2)



     Page 50                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          manpage on your system), then    you should use the
          sysopen() function, which involves no    such magic.
          This is another way to protect your filenames    from
          interpretation.  For example:

              use IO::Handle;
              sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
              or die "sysopen $path: $!";
              $oldfh = select(HANDLE); $| = 1; select($oldfh);
              print HANDLE "stuff $$\n");
              seek(HANDLE, 0, 0);
              print "File contains: ", <HANDLE>;

          Using    the constructor    from the IO::Handle package
          (or one of its subclasses, such as IO::File or
          IO::Socket), you can generate    anonymous filehandles
          that have the    scope of whatever variables hold
          references to    them, and automatically    close whenever
          and however you leave    that scope:

              use IO::File;
              #...
              sub read_myfile_munged {
              my $ALL = shift;
              my $handle = new IO::File;
              open($handle,    "myfile") or die "myfile: $!";
              $first = <$handle>
                  or return    ();    # Automatically    closed here.
              mung $first or die "mung failed";      # Or here.
              return $first, <$handle> if $ALL;      # Or here.
              $first;                  # Or here.
              }

          See the seek() entry elsewhere in this documentfor
          some details about mixing reading and    writing.

      opendir DIRHANDLE,EXPR
          Opens    a directory named EXPR for processing by
          readdir(), telldir(),    seekdir(), rewinddir(),    and
          closedir().  Returns TRUE if successful.  DIRHANDLEs
          have their own namespace separate from FILEHANDLEs.

      ord EXPR

      ord      Returns the numeric ascii value of the first
          character of EXPR.  If EXPR is omitted, uses $_.
          For the reverse, see the chr entry elsewhere in this
          document.

      pack TEMPLATE,LIST
          Takes    an array or list of values and packs it    into a
          binary structure, returning the string containing



     Page 51                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          the structure.  The TEMPLATE is a sequence of
          characters that give the order and type of values,
          as follows:

              A      An ascii string, will    be space padded.
              a      An ascii string, will    be null    padded.
              b      A bit    string (ascending bit order, like vec()).
              B      A bit    string (descending bit order).
              h      A hex    string (low nybble first).
              H      A hex    string (high nybble first).

              c      A signed char    value.
              C      An unsigned char value.

              s      A signed short value.
              S      An unsigned short value.
                (This 'short' is _exactly_ 16 bits,    which may differ from
                 what a local C compiler calls 'short'.)

              i      A signed integer value.
              I      An unsigned integer value.
                (This 'integer' is _at_least_ 32 bits wide.     Its exact
                 size depends on what a local C compiler calls 'int',
                 and may even be larger than the 'long' described in
                 the next item.)

              l      A signed long    value.
              L      An unsigned long value.
                (This 'long' is _exactly_ 32 bits, which may differ    from
                 what a local C compiler calls 'long'.)

              n      A short in "network" (big-endian) order.
              N      A long in "network" (big-endian) order.
              v      A short in "VAX" (little-endian) order.
              V      A long in "VAX" (little-endian) order.
                (These 'shorts' and    'longs'    are _exactly_ 16 bits and
                 _exactly_ 32 bits,    respectively.)

              f      A single-precision float in the native format.
              d      A double-precision float in the native format.

              p      A pointer to a null-terminated string.
              P      A pointer to a structure (fixed-length string).

              u      A uuencoded string.

              w      A BER    compressed integer.  Its bytes represent an unsigned
              integer in base 128, most significant    digit first, with as
              few digits as    possible.  Bit eight (the high bit) is set
              on each byte except the last.





     Page 52                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              x      A null byte.
              X      Back up a byte.
              @      Null fill to absolute    position.

          Each letter may optionally be    followed by a number
          giving a repeat count.  With all types except    "a",
          "A", "b", "B", "h", "H", and "P" the pack function
          will gobble up that many values from the LIST.  A *
          for the repeat count means to    use however many items
          are left.  The "a" and "A" types gobble just one
          value, but pack it as    a string of length count,
          padding with nulls or    spaces as necessary.  (When
          unpacking, "A" strips    trailing spaces    and nulls, but
          "a" does not.)  Likewise, the    "b" and    "B" fields
          pack a string    that many bits long.  The "h" and "H"
          fields pack a    string that many nybbles long.    The
          "p" type packs a pointer to a    null- terminated
          string.  You are responsible for ensuring the    string
          is not a temporary value (which can potentially get
          deallocated before you get around to using the
          packed result).  The "P" packs a pointer to a
          structure of the size    indicated by the length. A
          NULL pointer is created if the corresponding value
          for "p" or "P" is undef.  Real numbers (floats and
          doubles) are in the native machine format only; due
          to the multiplicity of floating formats around, and
          the lack of a    standard "network" representation, no
          facility for interchange has been made.  This    means
          that packed floating point data written on one
          machine may not be readable on another - even    if
          both use IEEE    floating point arithmetic (as the
          endian-ness of the memory representation is not part
          of the IEEE spec).  Note that    Perl uses doubles
          internally for all numeric calculation, and
          converting from double into float and    thence back to
          double again will lose precision (i.e., unpack("f",
          pack("f", $foo)) will    not in general equal $foo).

          Examples:

              $foo = pack("cccc",65,66,67,68);
              #    foo eq "ABCD"
              $foo = pack("c4",65,66,67,68);
              #    same thing

              $foo = pack("ccxxcc",65,66,67,68);
              #    foo eq "AB\0\0CD"

              $foo = pack("s2",1,2);
              #    "\1\0\2\0" on little-endian
              #    "\0\1\0\2" on big-endian




     Page 53                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              $foo = pack("a4","abcd","x","y","z");
              #    "abcd"

              $foo = pack("aaaa","abcd","x","y","z");
              #    "axyz"

              $foo = pack("a14","abcdefg");
              #    "abcdefg\0\0\0\0\0\0\0"

              $foo = pack("i9pl", gmtime);
              #    a real struct tm (on my    system anyway)

              sub bintodec {
              unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
              }

          The same template may    generally also be used in the
          unpack function.

      package

      package NAMESPACE
          Declares the compilation unit    as being in the    given
          namespace.  The scope    of the package declaration is
          from the declaration itself through the end of the
          enclosing block (the same scope as the local()
          operator).  All further unqualified dynamic
          identifiers will be in this namespace.  A package
          statement affects only dynamic variables--including
          those    you've used local() on--but _n_o_t    lexical
          variables created with my().    Typically it would be
          the first declaration    in a file to be    included by
          the require or use operator.    You can    switch into a
          package in more than one place; it merely influences
          which    symbol table is    used by    the compiler for the
          rest of that block.  You can refer to    variables and
          filehandles in other packages    by prefixing the
          identifier with the package name and a double    colon:
          $Package::Variable.  If the package name is null,
          the main package as assumed.    That is, $::sail is
          equivalent to    $main::sail.

          If NAMESPACE is omitted, then    there is no current
          package, and all identifiers must be fully qualified
          or lexicals.    This is    stricter than use strict,
          since    it also    extends    to function names.

          See the section on _P_a_c_k_a_g_e_s in the _p_e_r_l_m_o_d manpage
          for more information about packages, modules,    and
          classes.  See    the _p_e_r_l_s_u_b manpage for    other scoping
          issues.




     Page 54                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      pipe READHANDLE,WRITEHANDLE
          Opens    a pair of connected pipes like the
          corresponding    system call.  Note that    if you set up
          a loop of piped processes, deadlock can occur    unless
          you are very careful.     In addition, note that    Perl's
          pipes    use stdio buffering, so    you may    need to    set $|
          to flush your    WRITEHANDLE after each command,
          depending on the application.

          See the _I_P_C::_O_p_e_n_2 manpage, the _I_P_C::_O_p_e_n_3 manpage,
          and the section on _B_i_d_i_r_e_c_t_i_o_n_a_l _C_o_m_m_u_n_i_c_a_t_i_o_n in
          the _p_e_r_l_i_p_c manpage for examples of such things.

      pop ARRAY

      pop      Pops and returns the last value of the array,
          shortening the array by 1.  Has a similar effect to

              $tmp = $ARRAY[$#ARRAY--];

          If there are no elements in the array, returns the
          undefined value.  If ARRAY is    omitted, pops the
          @ARGV    array in the main program, and the @_ array in
          subroutines, just like shift().

      pos SCALAR

      pos      Returns the offset of    where the last m//g search
          left off for the variable is in question ($_ is used
          when the variable is not specified).    May be
          modified to change that offset.  Such    modification
          will also influence the \G zero-width    assertion in
          regular expressions.    See the    _p_e_r_l_r_e manpage and the
          _p_e_r_l_o_p manpage.

      print    FILEHANDLE LIST

      print    LIST

      print      Prints a string or a comma-separated list of
          strings.  Returns TRUE if successful.     FILEHANDLE
          may be a scalar variable name, in which case the
          variable contains the    name of    or a reference to the
          filehandle, thus introducing one level of
          indirection.    (NOTE: If FILEHANDLE is    a variable and
          the next token is a term, it may be misinterpreted
          as an    operator unless    you interpose a    + or put
          parentheses around the arguments.)  If FILEHANDLE is
          omitted, prints by default to    standard output    (or to
          the last selected output channel--see    the select
          entry    elsewhere in this document).  If LIST is also
          omitted, prints $_ to    the currently selected output



     Page 55                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          channel.  To set the default output channel to
          something other than STDOUT use the select
          operation.  Note that, because print takes a LIST,
          anything in the LIST is evaluated in list context,
          and any subroutine that you call will    have one or
          more of its expressions evaluated in list context.
          Also be careful not to follow    the print keyword with
          a left parenthesis unless you    want the corresponding
          right    parenthesis to terminate the arguments to the
          print--interpose a + or put parentheses around all
          the arguments.

          Note that if you're storing FILEHANDLES in an    array
          or other expression, you will    have to    use a block
          returning its    value instead:

              print { $files[$i] } "stuff\n";
              print { $OK ? STDOUT : STDERR } "stuff\n";


      printf FILEHANDLE FORMAT, LIST

      printf FORMAT, LIST
          Equivalent to    print FILEHANDLE sprintf(FORMAT,
          LIST), except    that $\    (the output record separator)
          is not appended.  The    first argument of the list
          will be interpreted as the printf() format.  If use
          locale is in effect, the character used for the
          decimal point    in formatted real numbers is affected
          by the LC_NUMERIC locale.  See the _p_e_r_l_l_o_c_a_l_e
          manpage.

          Don't    fall into the trap of using a printf() when a
          simple print() would do.  The    print()    is more
          efficient and    less error prone.

      prototype FUNCTION
          Returns the prototype    of a function as a string (or
          undef    if the function    has no prototype).  FUNCTION
          is a reference to, or    the name of, the function
          whose    prototype you want to retrieve.

          If FUNCTION is a string starting with    CORE::,    the
          rest is taken    as a name for Perl builtin.  If
          builtin is not _o_v_e_r_r_i_d_a_b_l_e (such as qw//) or its
          arguments cannot be expressed    by a prototype (such
          as system()) - in other words, the builtin does not
          behave like a    Perl function -    returns    undef.
          Otherwise, the string    describing the equivalent
          prototype is returned.





     Page 56                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      push ARRAY,LIST
          Treats ARRAY as a stack, and pushes the values of
          LIST onto the    end of ARRAY.  The length of ARRAY
          increases by the length of LIST.  Has    the same
          effect as

              for $value (LIST)    {
              $ARRAY[++$#ARRAY] = $value;
              }

          but is more efficient.  Returns the new number of
          elements in the array.

      q/STRING/

      qq/STRING/

      qr/STRING/

      qx/STRING/

      qw/STRING/
          Generalized quotes.  See the _p_e_r_l_o_p manpage.

      quotemeta EXPR

      quotemeta
          Returns the value of EXPR with all non-alphanumeric
          characters backslashed.  (That is, all characters
          not matching /[A-Za-z_0-9]/ will be preceded by a
          backslash in the returned string, regardless of any
          locale settings.)  This is the internal function
          implementing the \Q escape in    double-quoted strings.

          If EXPR is omitted, uses $_.

      rand EXPR

      rand      Returns a random fractional number greater than or
          equal    to 0 and less than the value of    EXPR.  (EXPR
          should be positive.)    If EXPR    is omitted, the    value
          1 is used.  Automatically calls srand() unless
          srand() has already been called.  See    also srand().

          (Note: If your rand function consistently returns
          numbers that are too large or    too small, then    your
          version of Perl was probably compiled    with the wrong
          number of RANDBITS.)

      read FILEHANDLE,SCALAR,LENGTH,OFFSET





     Page 57                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      read FILEHANDLE,SCALAR,LENGTH
          Attempts to read LENGTH bytes    of data    into variable
          SCALAR from the specified FILEHANDLE.     Returns the
          number of bytes actually read, 0 at end of file, or
          undef    if there was an    error.    SCALAR will be grown
          or shrunk to the length actually read.  An OFFSET
          may be specified to place the    read data at some
          other    place than the beginning of the    string.     This
          call is actually implemented in terms    of stdio's
          _f_r_e_a_d(3) call.  To get a true    _r_e_a_d(2)    system call,
          see sysread().

      readdir DIRHANDLE
          Returns the next directory entry for a directory
          opened by opendir().    If used    in list    context,
          returns all the rest of the entries in the
          directory.  If there are no more entries, returns an
          undefined value in scalar context or a null list in
          list context.

          If you're planning to    filetest the return values out
          of a readdir(), you'd    better prepend the directory
          in question.    Otherwise, because we didn't chdir()
          there, it would have been testing the    wrong file.

              opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
              @dots = grep { /^\./ && -f "$some_dir/$_"    } readdir(DIR);
              closedir DIR;


      readline EXPR
          Reads    from the filehandle whose typeglob is
          contained in EXPR.  In scalar    context, a single line
          is read and returned.     In list context, reads    until
          end-of-file is reached and returns a list of lines
          (however you've defined lines    with $/    or
          $INPUT_RECORD_SEPARATOR).  This is the internal
          function implementing    the <EXPR> operator, but you
          can use it directly.    The <EXPR> operator is
          discussed in more detail in the section on _I/_O
          _O_p_e_r_a_t_o_r_s in the _p_e_r_l_o_p manpage.

              $line = <STDIN>;
              $line = readline(*STDIN);          # same thing


      readlink EXPR

      readlink
          Returns the value of a symbolic link,    if symbolic
          links    are implemented.  If not, gives    a fatal    error.
          If there is some system error, returns the undefined



     Page 58                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          value    and sets $! (errno).  If EXPR is omitted, uses
          $_.

      readpipe EXPR
          EXPR is executed as a    system command.     The collected
          standard output of the command is returned.  In
          scalar context, it comes back    as a single
          (potentially multi-line) string.  In list context,
          returns a list of lines (however you've defined
          lines    with $/    or $INPUT_RECORD_SEPARATOR).  This is
          the internal function    implementing the qx/EXPR/
          operator, but    you can    use it directly.  The qx/EXPR/
          operator is discussed    in more    detail in the section
          on _I/_O _O_p_e_r_a_t_o_r_s in the _p_e_r_l_o_p manpage.

      recv SOCKET,SCALAR,LEN,FLAGS
          Receives a message on    a socket.  Attempts to receive
          LENGTH bytes of data into variable SCALAR from the
          specified SOCKET filehandle.    Actually does a    C
          recvfrom(), so that it can return the    address    of the
          sender.  Returns the undefined value if there's an
          error.  SCALAR will be grown or shrunk to the    length
          actually read.  Takes    the same flags as the system
          call of the same name.  See the section on _U_D_P:
          _M_e_s_s_a_g_e _P_a_s_s_i_n_g in the _p_e_r_l_i_p_c manpage for examples.

      redo LABEL

      redo      The redo command restarts the    loop block without
          evaluating the conditional again.  The continue
          block, if any, is not    executed.  If the LABEL    is
          omitted, the command refers to the innermost
          enclosing loop.  This    command    is normally used by
          programs that    want to    lie to themselves about    what
          was just input:

              #    a simpleminded Pascal comment stripper
              #    (warning: assumes no { or } in strings)
              LINE: while (<STDIN>) {
              while    (s|({.*}.*){.*}|$1 |) {}
              s|{.*}| |;
              if (s|{.*| |)    {
                  $front = $_;
                  while (<STDIN>) {
                  if (/}/) {      # end    of comment?
                      s|^|$front\{|;
                      redo LINE;
                  }
                  }
              }
              print;
              }



     Page 59                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          See also the continue    entry elsewhere    in this
          documentfor an illustration of how last, next, and
          redo work.

      ref EXPR

      ref      Returns a TRUE value if EXPR is a reference, FALSE
          otherwise.  If EXPR is not specified,    $_ will    be
          used.     The value returned depends on the type    of
          thing    the reference is a reference to.  Builtin
          types    include:

              REF
              SCALAR
              ARRAY
              HASH
              CODE
              GLOB

          If the referenced object has been blessed into a
          package, then    that package name is returned instead.
          You can think    of ref() as a typeof() operator.

              if (ref($r) eq "HASH") {
              print    "r is a    reference to a hash.\n";
              }
              if (!ref($r)) {
              print    "r is not a reference at all.\n";
              }

          See also the _p_e_r_l_r_e_f manpage.

      rename OLDNAME,NEWNAME
          Changes the name of a    file.  Returns 1 for success,
          0 otherwise.    Will not work across file system
          boundaries.

      require EXPR

      require Demands some semantics specified by EXPR, or by $_
          if EXPR is not supplied.  If EXPR is numeric,
          demands that the current version of Perl ($] or
          $PERL_VERSION) be equal or greater than EXPR.

          Otherwise, demands that a library file be included
          if it    hasn't already been included.  The file    is
          included via the do-FILE mechanism, which is
          essentially just a variety of    eval().     Has semantics
          similar to the following subroutine:






     Page 60                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              sub require {
              my($filename)    = @_;
              return 1 if $INC{$filename};
              my($realfilename,$result);
              ITER:    {
                  foreach $prefix (@INC) {
                  $realfilename    = "$prefix/$filename";
                  if (-f $realfilename)    {
                      $result =    do $realfilename;
                      last ITER;
                  }
                  }
                  die "Can't find $filename    in \@INC";
              }
              die $@ if $@;
              die "$filename did not return    true value" unless $result;
              $INC{$filename} = $realfilename;
              return $result;
              }

          Note that the    file will not be included twice    under
          the same specified name.  The    file must return TRUE
          as the last statement    to indicate successful
          execution of any initialization code,    so it's
          customary to end such    a file with "1;" unless    you're
          sure it'll return TRUE otherwise.  But it's better
          just to put the "1;",    in case    you add    more
          statements.

          If EXPR is a bareword, the require assumes a "._p_m"
          extension and    replaces "::" with "/" in the filename
          for you, to make it easy to load standard modules.
          This form of loading of modules does not risk
          altering your    namespace.

          In other words, if you try this:

              require Foo::Bar;    # a splendid bareword

          The require function will actually look for the
          "_F_o_o/_B_a_r._p_m" file in the directories specified in
          the @INC array.

          But if you try this:

              $class = 'Foo::Bar';
              require $class;      # $class    is not a bareword
              #or
              require "Foo::Bar";  # not a bareword    because    of the ""

          The require function will look for the "_F_o_o::_B_a_r"
          file in the @INC array and will complain about not



     Page 61                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          finding "_F_o_o::_B_a_r" there. In this case you can do:

              eval "require    $class";

          For a    yet-more-powerful import facility, see the use
          entry    elsewhere in this document and the _p_e_r_l_m_o_d
          manpage.

      reset    EXPR

      reset      Generally used in a continue block at    the end    of a
          loop to clear    variables and reset ?? searches    so
          that they work again.     The expression    is interpreted
          as a list of single characters (hyphens allowed for
          ranges).  All    variables and arrays beginning with
          one of those letters are reset to their pristine
          state.  If the expression is omitted,    one-match
          searches (?pattern?) are reset to match again.
          Resets only variables    or searches in the current
          package.  Always returns 1.  Examples:

              reset 'X';      # reset all X    variables
              reset 'a-z';      # reset lower    case variables
              reset;          # just reset ?? searches

          Resetting "A-Z" is not recommended because you'll
          wipe out your    @ARGV and @INC arrays and your %ENV
          hash.     Resets    only package variables--lexical
          variables are    unaffected, but    they clean themselves
          up on    scope exit anyway, so you'll probably want to
          use them instead.  See the my    entry elsewhere    in
          this document.

      return EXPR

      return  Returns from a subroutine, eval(), or    do FILE    with
          the value given in EXPR.  Evaluation of EXPR may be
          in list, scalar, or void context, depending on how
          the return value will    be used, and the context may
          vary from one    execution to the next (see
          wantarray()).     If no EXPR is given, returns an empty
          list in list context,    an undefined value in scalar
          context, or nothing in a void    context.

          (Note    that in    the absence of a return, a subroutine,
          eval,    or do FILE will    automatically return the value
          of the last expression evaluated.)

      reverse LIST
          In list context, returns a list value    consisting of
          the elements of LIST in the opposite order.  In
          scalar context, concatenates the elements of LIST,



     Page 62                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          and returns a    string value consisting    of those
          bytes, but in    the opposite order.

              print reverse <>;          # line tac, last line    first

              undef $/;              # for    efficiency of <>
              print scalar reverse <>;      # byte tac, last line    tsrif

          This operator    is also    handy for inverting a hash,
          although there are some caveats.  If a value is
          duplicated in    the original hash, only    one of those
          can be represented as    a key in the inverted hash.
          Also,    this has to unwind one hash and    build a    whole
          new one, which may take some time on a large hash.

              %by_name = reverse %by_address;      # Invert the hash


      rewinddir DIRHANDLE
          Sets the current position to the beginning of    the
          directory for    the readdir() routine on DIRHANDLE.

      rindex STR,SUBSTR,POSITION

      rindex STR,SUBSTR
          Works    just like index    except that it returns the
          position of the LAST occurrence of SUBSTR in STR.
          If POSITION is specified, returns the    last
          occurrence at    or before that position.

      rmdir    FILENAME

      rmdir      Deletes the directory    specified by FILENAME if that
          directory is empty.  If it succeeds it returns TRUE,
          otherwise it returns FALSE and sets $! (errno).  If
          FILENAME is omitted, uses $_.

      s///      The substitution operator.  See the _p_e_r_l_o_p manpage.

      scalar EXPR
          Forces EXPR to be interpreted    in scalar context and
          returns the value of EXPR.

              @counts =    ( scalar @a, scalar @b,    scalar @c );

          There    is no equivalent operator to force an
          expression to    be interpolated    in list    context
          because it's in practice never needed.  If you
          really wanted    to do so, however, you could use the
          construction @{[ (some expression) ]}, but usually a
          simple (some expression) suffices.




     Page 63                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      seek FILEHANDLE,POSITION,WHENCE
          Sets FILEHANDLE's position, just like    the fseek()
          call of stdio().  FILEHANDLE may be an expression
          whose    value gives the    name of    the filehandle.     The
          values for WHENCE are    0 to set the new position to
          POSITION, 1 to set it    to the current position    plus
          POSITION, and    2 to set it to EOF plus    POSITION
          (typically negative).     For WHENCE you    may use    the
          constants SEEK_SET, SEEK_CUR,    and SEEK_END from
          either the IO::Seekable or the POSIX module.
          Returns 1 upon success, 0 otherwise.

          If you want to position file for sysread() or
          syswrite(), don't use    seek() -- buffering makes its
          effect on the    file's system position unpredictable
          and non-portable.  Use sysseek() instead.

          On some systems you have to do a seek    whenever you
          switch between reading and writing.  Amongst other
          things, this may have    the effect of calling stdio's
          _c_l_e_a_r_e_r_r(3).    A WHENCE of 1 (SEEK_CUR) is useful for
          not moving the file position:

              seek(TEST,0,1);

          This is also useful for applications emulating tail
          -f.  Once you    hit EOF    on your    read, and then sleep
          for a    while, you might have to stick in a _s_e_e_k() to
          reset    things.     The seek() doesn't change the current
          position, but    it _d_o_e_s    clear the end-of-file
          condition on the handle, so that the next <FILE>
          makes    Perl try again to read something.  We hope.

          If that doesn't work (some stdios are    particularly
          cantankerous), then you may need something more like
          this:

              for (;;) {
              for ($curpos = tell(FILE); $_    = <FILE>;
                   $curpos = tell(FILE)) {
                  #    search for some    stuff and put it into files
              }
              sleep($for_a_while);
              seek(FILE, $curpos, 0);
              }


      seekdir DIRHANDLE,POS
          Sets the current position for    the readdir() routine
          on DIRHANDLE.     POS must be a value returned by
          telldir().  Has the same caveats about possible
          directory compaction as the corresponding system



     Page 64                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          library routine.

      select FILEHANDLE

      select  Returns the currently    selected filehandle.  Sets the
          current default filehandle for output, if FILEHANDLE
          is supplied.    This has two effects: first, a write()
          or a print() without a filehandle will default to
          this FILEHANDLE.  Second, references to variables
          related to output will refer to this output channel.
          For example, if you have to set the top of form
          format for more than one output channel, you might
          do the following:

              select(REPORT1);
              $^ = 'report1_top';
              select(REPORT2);
              $^ = 'report2_top';

          FILEHANDLE may be an expression whose    value gives
          the name of the actual filehandle.  Thus:

              $oldfh = select(STDERR); $| = 1; select($oldfh);

          Some programmers may prefer to think of filehandles
          as objects with methods, preferring to write the
          last example as:

              use IO::Handle;
              STDERR->autoflush(1);


      select RBITS,WBITS,EBITS,TIMEOUT
          This calls the _s_e_l_e_c_t(2) system call with the    bit
          masks    specified, which can be    constructed using
          fileno() and vec(), along these lines:

              $rin = $win = $ein = '';
              vec($rin,fileno(STDIN),1)    = 1;
              vec($win,fileno(STDOUT),1) = 1;
              $ein = $rin | $win;

          If you want to select    on many    filehandles you    might
          wish to write    a subroutine:











     Page 65                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              sub fhbits {
              my(@fhlist) =    split('    ',$_[0]);
              my($bits);
              for (@fhlist)    {
                  vec($bits,fileno($_),1) =    1;
              }
              $bits;
              }
              $rin = fhbits('STDIN TTY SOCK');

          The usual idiom is:

              ($nfound,$timeleft) =
            select($rout=$rin, $wout=$win, $eout=$ein, $timeout);

          or to    block until something becomes ready just do
          this

              $nfound =    select($rout=$rin, $wout=$win, $eout=$ein, undef);

          Most systems do not bother to    return anything    useful
          in $timeleft,    so calling _s_e_l_e_c_t() in scalar context
          just returns $nfound.

          Any of the bit masks can also    be undef.  The
          timeout, if specified, is in seconds,    which may be
          fractional.  Note: not all implementations are
          capable of returning the$timeleft.  If not, they
          always return    $timeleft equal    to the supplied
          $timeout.

          You can effect a sleep of 250    milliseconds this way:

              select(undef, undef, undef, 0.25);

          WWWWAAAARRRRNNNNIIIINNNNGGGG: One should not attempt to mix buffered I/O
          (like    read() or <FH>)    with select(), except as
          permitted by POSIX, and even then only on POSIX
          systems.  You    have to    use sysread() instead.

      semctl ID,SEMNUM,CMD,ARG
          Calls    the System V IPC function semctl().  You'll
          probably have    to say

              use IPC::SysV;

          first    to get the correct constant definitions.  If
          CMD is IPC_STAT or GETALL, then ARG must be a
          variable which will hold the returned    semid_ds
          structure or semaphore value array.  Returns like
          ioctl(): the undefined value for error, "0 but true"
          for zero, or the actual return value otherwise.  See



     Page 66                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          also IPC::SysV and IPC::Semaphore documentation.

      semget KEY,NSEMS,FLAGS
          Calls    the System V IPC function semget.  Returns the
          semaphore id,    or the undefined value if there    is an
          error.  See also IPC::SysV and IPC::SysV::Semaphore
          documentation.

      semop    KEY,OPSTRING
          Calls    the System V IPC function semop    to perform
          semaphore operations such as signaling and waiting.
          OPSTRING must    be a packed array of semop structures.
          Each semop structure can be generated    with
          pack("sss", $semnum, $semop, $semflag).  The number
          of semaphore operations is implied by    the length of
          OPSTRING.  Returns TRUE if successful, or FALSE if
          there    is an error.  As an example, the following
          code waits on    semaphore $semnum of semaphore id
          $semid:

              $semop = pack("sss", $semnum, -1,    0);
              die "Semaphore trouble: $!\n" unless semop($semid, $semop);

          To signal the    semaphore, replace -1 with 1.  See
          also IPC::SysV and IPC::SysV::Semaphore
          documentation.

      send SOCKET,MSG,FLAGS,TO

      send SOCKET,MSG,FLAGS
          Sends    a message on a socket.    Takes the same flags
          as the system    call of    the same name.    On unconnected
          sockets you must specify a destination to send TO,
          in which case    it does    a C sendto().  Returns the
          number of characters sent, or    the undefined value if
          there    is an error.  See the section on _U_D_P: _M_e_s_s_a_g_e
          _P_a_s_s_i_n_g in the _p_e_r_l_i_p_c manpage for examples.

      setpgrp PID,PGRP
          Sets the current process group for the specified
          PID, 0 for the current process.  Will    produce    a
          fatal    error if used on a machine that    doesn't
          implement _s_e_t_p_g_r_p(2).     If the    arguments are omitted,
          it defaults to 0,0.  Note that the POSIX version of
          setpgrp() does not accept any    arguments, so only
          setpgrp 0,0 is portable.

      setpriority WHICH,WHO,PRIORITY
          Sets the current priority for    a process, a process
          group, or a user.  (See _s_e_t_p_r_i_o_r_i_t_y(2).)  Will
          produce a fatal error    if used    on a machine that
          doesn't implement _s_e_t_p_r_i_o_r_i_t_y(2).



     Page 67                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
          Sets the socket option requested.  Returns undefined
          if there is an error.     OPTVAL    may be specified as
          undef    if you don't want to pass an argument.

      shift    ARRAY

      shift      Shifts the first value of the    array off and returns
          it, shortening the array by 1    and moving everything
          down.     If there are no elements in the array,
          returns the undefined    value.    If ARRAY is omitted,
          shifts the @_    array within the lexical scope of
          subroutines and formats, and the @ARGV array at file
          scopes or within the lexical scopes established by
          the eval '', BEGIN {}, END {}, and INIT {}
          constructs.  See also    unshift(), push(), and pop().
          Shift() and unshift()    do the same thing to the left
          end of an array that pop() and push()    do to the
          right    end.

      shmctl ID,CMD,ARG
          Calls    the System V IPC function shmctl.  You'll
          probably have    to say

              use IPC::SysV;

          first    to get the correct constant definitions.  If
          CMD is IPC_STAT, then    ARG must be a variable which
          will hold the    returned shmid_ds structure.  Returns
          like ioctl: the undefined value for error, "0    but
          true"    for zero, or the actual    return value
          otherwise.  See also IPC::SysV documentation.

      shmget KEY,SIZE,FLAGS
          Calls    the System V IPC function shmget.  Returns the
          shared memory    segment    id, or the undefined value if
          there    is an error.  See also IPC::SysV
          documentation.

      shmread ID,VAR,POS,SIZE

      shmwrite ID,STRING,POS,SIZE
          Reads    or writes the System V shared memory segment
          ID starting at position POS for size SIZE by
          attaching to it, copying in/out, and detaching from
          it.  When reading, VAR must be a variable that will
          hold the data    read.  When writing, if    STRING is too
          long,    only SIZE bytes    are used; if STRING is too
          short, nulls are written to fill out SIZE bytes.
          Return TRUE if successful, or    FALSE if there is an
          error.  See also IPC::SysV documentation.




     Page 68                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      shutdown SOCKET,HOW
          Shuts    down a socket connection in the    manner
          indicated by HOW, which has the same interpretation
          as in    the system call    of the same name.

              shutdown(SOCKET, 0);    #    I/we have stopped reading data
              shutdown(SOCKET, 1);    #    I/we have stopped writing data
              shutdown(SOCKET, 2);    #    I/we have stopped using    this socket

          This is useful with sockets when you want to tell
          the other side you're    done writing but not done
          reading, or vice versa.  It's    also a more insistent
          form of close    because    it also    disables the
          filedescriptor in any    forked copies in other
          processes.

      sin EXPR

      sin      Returns the sine of EXPR (expressed in radians).  If
          EXPR is omitted, returns sine    of $_.

          For the inverse sine operation, you may use the
          POSIX::asin()    function, or use this relation:

              sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }


      sleep    EXPR

      sleep      Causes the script to sleep for EXPR seconds, or
          forever if no    EXPR.  May be interrupted if the
          process receives a signal such as SIGALRM.  Returns
          the number of    seconds    actually slept.     You probably
          cannot mix alarm() and sleep() calls,    because
          sleep() is often implemented using alarm().

          On some older    systems, it may    sleep up to a full
          second less than what    you requested, depending on
          how it counts    seconds.  Most modern systems always
          sleep    the full amount.  They may appear to sleep
          longer than that, however, because your process
          might    not be scheduled right away in a busy
          multitasking system.

          For delays of    finer granularity than one second, you
          may use Perl's syscall() interface to    access
          _s_e_t_i_t_i_m_e_r(2) if your system supports it, or else see
          the select() entry elsewhere in this documentabove.

          See also the POSIX module's sigpause() function.





     Page 69                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      socket SOCKET,DOMAIN,TYPE,PROTOCOL
          Opens    a socket of the    specified kind and attaches it
          to filehandle    SOCKET.     DOMAIN, TYPE, and PROTOCOL
          are specified    the same as for    the system call    of the
          same name.  You should "use Socket;" first to    get
          the proper definitions imported.  See    the example in
          the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r    _C_o_m_m_u_n_i_c_a_t_i_o_n
          in the _p_e_r_l_i_p_c manpage.

      socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
          Creates an unnamed pair of sockets in    the specified
          domain, of the specified type.  DOMAIN, TYPE,    and
          PROTOCOL are specified the same as for the system
          call of the same name.  If unimplemented, yields a
          fatal    error.    Returns    TRUE if    successful.

          Some systems defined pipe() in terms of
          socketpair(),    in which a call    to pipe(Rdr, Wtr) is
          essentially:

              use Socket;
              socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
              shutdown(Rdr, 1);           # no more writing for reader
              shutdown(Wtr, 0);           # no more reading for writer

          See the _p_e_r_l_i_p_c manpage for an example of socketpair
          use.

      sort SUBNAME LIST

      sort BLOCK LIST

      sort LIST
          Sorts    the LIST and returns the sorted    list value.
          If SUBNAME or    BLOCK is omitted, sort()s in standard
          string comparison order.  If SUBNAME is specified,
          it gives the name of a subroutine that returns an
          integer less than, equal to, or greater than 0,
          depending on how the elements    of the array are to be
          ordered.  (The <=> and cmp operators are extremely
          useful in such routines.)  SUBNAME may be a scalar
          variable name    (unsubscripted), in which case the
          value    provides the name of (or a reference to) the
          actual subroutine to use.  In    place of a SUBNAME,
          you can provide a BLOCK as an    anonymous, in-line
          sort subroutine.

          In the interests of efficiency the normal calling
          code for subroutines is bypassed, with the following
          effects: the subroutine may not be a recursive
          subroutine, and the two elements to be compared are
          passed into the subroutine not via @_    but as the



     Page 70                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          package global variables $a and $b (see example
          below).  They    are passed by reference, so don't
          modify $a and    $b.  And don't try to declare them as
          lexicals either.

          You also cannot exit out of the sort block or
          subroutine using any of the loop control operators
          described in the _p_e_r_l_s_y_n manpage or with goto().

          When use locale is in    effect,    sort LIST sorts    LIST
          according to the current collation locale.  See the
          _p_e_r_l_l_o_c_a_l_e manpage.

          Examples:

              #    sort lexically
              @articles    = sort @files;

              #    same thing, but    with explicit sort routine
              @articles    = sort {$a cmp $b} @files;

              #    now case-insensitively
              @articles    = sort {uc($a) cmp uc($b)} @files;

              #    same thing in reversed order
              @articles    = sort {$b cmp $a} @files;

              #    sort numerically ascending
              @articles    = sort {$a <=> $b} @files;

              #    sort numerically descending
              @articles    = sort {$b <=> $a} @files;

              #    sort using explicit subroutine name
              sub byage    {
              $age{$a} <=> $age{$b};  # presuming numeric
              }
              @sortedclass = sort byage    @class;

              #    this sorts the %age hash by value instead of key
              #    using an in-line function
              @eldest =    sort { $age{$b}    <=> $age{$a} } keys %age;

              sub backwards { $b cmp $a; }
              @harry = ('dog','cat','x','Cain','Abel');
              @george =    ('gone','chased','yz','Punished','Axed');
              print sort @harry;
                  #    prints AbelCaincatdogx
              print sort backwards @harry;
                  #    prints xdogcatCainAbel
              print sort @george, 'to',    @harry;
                  #    prints AbelAxedCainPunishedcatchaseddoggonetoxyz



     Page 71                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              #    inefficiently sort by descending numeric compare using
              #    the first integer after    the first = sign, or the
              #    whole record case-insensitively    otherwise

              @new = sort {
              ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
                          ||
                      uc($a)  cmp  uc($b)
              }    @old;

              #    same thing, but    much more efficiently;
              #    we'll build auxiliary indices instead
              #    for speed
              @nums = @caps = ();
              for (@old) {
              push @nums, /=(\d+)/;
              push @caps, uc($_);
              }

              @new = @old[ sort    {
                      $nums[$b] <=>    $nums[$a]
                           ||
                      $caps[$a] cmp    $caps[$b]
                     } 0..$#old
                 ];

              #    same thing using a Schwartzian Transform (no temps)
              @new = map { $_->[0] }
              sort { $b->[1] <=> $a->[1]
                      ||
                 $a->[2] cmp $b->[2]
              } map    { [$_, /=(\d+)/, uc($_)] } @old;

          If you're using strict, you _M_U_S_T _N_O_T declare $a and
          $b as    lexicals.  They    are package globals.  That
          means    if you're in the main package, it's

              @articles    = sort {$main::b <=> $main::a} @files;

          or just

              @articles    = sort {$::b <=> $::a} @files;

          but if you're    in the FooPack package,    it's

              @articles    = sort {$FooPack::b <=>    $FooPack::a} @files;

          The comparison function is required to behave.  If
          it returns inconsistent results (sometimes saying
          $x[1]    is less    than $x[2] and sometimes saying    the
          opposite, for    example) the results are not well-
          defined.



     Page 72                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      splice ARRAY,OFFSET,LENGTH,LIST

      splice ARRAY,OFFSET,LENGTH

      splice ARRAY,OFFSET
          Removes the elements designated by OFFSET and    LENGTH
          from an array, and replaces them with    the elements
          of LIST, if any.  In list context, returns the
          elements removed from    the array.  In scalar context,
          returns the last element removed, or undef if    no
          elements are removed.     The array grows or shrinks as
          necessary.  If OFFSET    is negative then it start that
          far from the end of the array.  If LENGTH is
          omitted, removes everything from OFFSET onward.  If
          LENGTH is negative, leave that many elements off the
          end of the array.  The following equivalences    hold
          (assuming $[ == 0):

              push(@a,$x,$y)      splice(@a,@a,0,$x,$y)
              pop(@a)          splice(@a,-1)
              shift(@a)          splice(@a,0,1)
              unshift(@a,$x,$y)      splice(@a,0,0,$x,$y)
              $a[$x] = $y      splice(@a,$x,1,$y)

          Example, assuming array lengths are passed before
          arrays:

              sub aeq {      # compare two    list values
              my(@a) = splice(@_,0,shift);
              my(@b) = splice(@_,0,shift);
              return 0 unless @a ==    @b;      # same len?
              while    (@a) {
                  return 0 if pop(@a) ne pop(@b);
              }
              return 1;
              }
              if (&aeq($len,@foo[1..$len],0+@bar,@bar))    { ... }


      split    /PATTERN/,EXPR,LIMIT

      split    /PATTERN/,EXPR

      split    /PATTERN/

      split      Splits a string into an array    of strings, and
          returns it.  By default, empty leading fields    are
          preserved, and empty trailing    ones are deleted.

          If not in list context, returns the number of    fields
          found    and splits into    the @_ array.  (In list
          context, you can force the split into    @_ by using ??



     Page 73                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          as the pattern delimiters, but it still returns the
          list value.)    The use    of implicit split to @_    is
          deprecated, however, because it clobbers your
          subroutine arguments.

          If EXPR is omitted, splits the $_ string.  If
          PATTERN is also omitted, splits on whitespace    (after
          skipping any leading whitespace).  Anything matching
          PATTERN is taken to be a delimiter separating    the
          fields.  (Note that the delimiter may    be longer than
          one character.)

          If LIMIT is specified    and positive, splits into no
          more than that many fields (though it    may split into
          fewer).  If LIMIT is unspecified or zero, trailing
          null fields are stripped (which potential users of
          pop()    would do well to remember).  If    LIMIT is
          negative, it is treated as if    an arbitrarily large
          LIMIT    had been specified.

          A pattern matching the null string (not to be
          confused with    a null pattern //, which is just one
          member of the    set of patterns    matching a null
          string) will split the value of EXPR into separate
          characters at    each point it matches that way.     For
          example:

              print join(':', split(/ */, 'hi there'));

          produces the output 'h:i:t:h:e:r:e'.

          The LIMIT parameter can be used to split a line
          partially

              ($login, $passwd,    $remainder) = split(/:/, $_, 3);

          When assigning to a list, if LIMIT is    omitted, Perl
          supplies a LIMIT one larger than the number of
          variables in the list, to avoid unnecessary work.
          For the list above LIMIT would have been 4 by
          default.  In time critical applications it behooves
          you not to split into    more fields than you really
          need.

          If the PATTERN contains parentheses, additional
          array    elements are created from each matching
          substring in the delimiter.

              split(/([,-])/, "1-10,20", 3);

          produces the list value




     Page 74                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              (1, '-', 10, ',',    20)

          If you had the entire    header of a normal Unix    email
          message in $header, you could    split it up into
          fields and their values this way:

              $header =~ s/\n\s+/ /g;  # fix continuation lines
              %hdrs   =     (UNIX_FROM => split /^(\S*?):\s*/m, $header);

          The pattern /PATTERN/    may be replaced    with an
          expression to    specify    patterns that vary at runtime.
          (To do runtime compilation only once,    use
          /$variable/o.)

          As a special case, specifying    a PATTERN of space ('
          ') will split    on white space just as split() with no
          arguments does.  Thus, split(' ') can    be used    to
          emulate aaaawwwwkkkk's    default    behavior, whereas split(/ /)
          will give you    as many    null initial fields as there
          are leading spaces.  A split() on /\s+/ is like a
          split(' ') except that any leading whitespace
          produces a null first    field.    A split() with no
          arguments really does    a split(' ', $_) internally.

          Example:

              open(PASSWD, '/etc/passwd');
              while (<PASSWD>) {
              ($login, $passwd, $uid, $gid,
               $gcos, $home, $shell) = split(/:/);
              #...
              }

          (Note    that $shell above will still have a newline on
          it.  See the chop, chomp,  and join entries
          elsewhere in this document.)

      sprintf FORMAT, LIST
          Returns a string formatted by    the usual printf()
          conventions of the C library function    sprintf().
          See the _s_p_r_i_n_t_f(_3) manpage or    the _p_r_i_n_t_f(_3) manpage
          on your system for an    explanation of the general
          principles.

          Perl does its    own sprintf() formatting -- it
          emulates the C function sprintf(), but it doesn't
          use it (except for floating-point numbers, and even
          then only the    standard modifiers are allowed).  As a
          result, any non-standard extensions in your local
          sprintf() are    not available from Perl.

          Perl's sprintf() permits the following universally-



     Page 75                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          known    conversions:

             %%      a percent sign
             %c      a character with the given number
             %s      a string
             %d      a signed integer, in decimal
             %u      an unsigned integer, in decimal
             %o      an unsigned integer, in octal
             %x      an unsigned integer, in hexadecimal
             %e      a floating-point number, in scientific notation
             %f      a floating-point number, in fixed decimal notation
             %g      a floating-point number, in %e or %f notation

          In addition, Perl permits the    following widely-
          supported conversions:

             %X      like %x, but using upper-case    letters
             %E      like %e, but using an    upper-case "E"
             %G      like %g, but with an upper-case "E" (if applicable)
             %p      a pointer (outputs the Perl value's address in hexadecimal)
             %n      special: *stores* the    number of characters output so far
              into the next    variable in the    parameter list

          Finally, for backward    (and we    do mean    "backward")
          compatibility, Perl permits these unnecessary    but
          widely-supported conversions:

             %i      a synonym for    %d
             %D      a synonym for    %ld
             %U      a synonym for    %lu
             %O      a synonym for    %lo
             %F      a synonym for    %f

          Perl permits the following universally-known flags
          between the %    and the    conversion letter:

             space   prefix positive number with a space
             +         prefix positive number with a plus    sign
             -         left-justify within the field
             0         use zeros,    not spaces, to right-justify
             #         prefix non-zero octal with    "0", non-zero hex with "0x"
             number  minimum field width
             .number "precision": digits after decimal point for
                 floating-point, max length    for string, minimum length
                 for integer
             l         interpret integer as C type "long"    or "unsigned long"
             h         interpret integer as C type "short" or "unsigned short"

          There    is also    one Perl-specific flag:

             V         interpret integer as Perl's standard integer type




     Page 76                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          Where    a number would appear in the flags, an
          asterisk ("*") may be    used instead, in which case
          Perl uses the    next item in the parameter list    as the
          given    number (that is, as the    field width or
          precision).  If a field width    obtained through "*"
          is negative, it has the same effect as the "-" flag:
          left-justification.

          If use locale    is in effect, the character used for
          the decimal point in formatted real numbers is
          affected by the LC_NUMERIC locale.  See the
          _p_e_r_l_l_o_c_a_l_e manpage.

      sqrt EXPR

      sqrt      Return the square root of EXPR.  If EXPR is omitted,
          returns square root of $_.

      srand    EXPR

      srand      Sets the random number seed for the rand() operator.
          If EXPR is omitted, uses a semi-random value based
          on the current time and process ID, among other
          things.  In versions of Perl prior to    5.004 the
          default seed was just    the current time().  This
          isn't    a particularly good seed, so many old programs
          supply their own seed    value (often time ^ $$ or time
          ^ ($$    + ($$ << 15))),    but that isn't necessary any
          more.

          In fact, it's    usually    not necessary to call srand()
          at all, because if it    is not called explicitly, it
          is called implicitly at the first use    of the rand()
          operator.  However, this was not the case in version
          of Perl before 5.004,    so if your script will run
          under    older Perl versions, it    should call srand().

          Note that you    need something much more random    than
          the default seed for cryptographic purposes.
          Checksumming the compressed output of    one or more
          rapidly changing operating system status programs is
          the usual method.  For example:

              srand (time ^ $$ ^ unpack    "%L*", `ps axww    | gzip`);

          If you're particularly concerned with    this, see the
          Math::TrulyRandom module in CPAN.

          Do _n_o_t call srand() multiple times in    your program
          unless you know exactly what you're doing and    why
          you're doing it.  The    point of the function is to
          "seed" the rand() function so    that rand() can



     Page 77                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          produce a different sequence each time you run your
          program.  Just do it once at the top of your
          program, or you _w_o_n'_t    get random numbers out of
          rand()!

          Frequently called programs (like CGI scripts)    that
          simply use

              time ^ $$

          for a    seed can fall prey to the mathematical
          property that

              a^b == (a+1)^(b+1)

          one-third of the time.  So don't do that.

      stat FILEHANDLE

      stat EXPR

      stat      Returns a 13-element list giving the status info for
          a file, either the file opened via FILEHANDLE, or
          named    by EXPR.  If EXPR is omitted, it stats $_.
          Returns a null list if the stat fails.  Typically
          used as follows:

              ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
             $atime,$mtime,$ctime,$blksize,$blocks)
                 = stat($filename);

          Not all fields are supported on all filesystem
          types.  Here are the meaning of the fields:

            0 dev      device number of    filesystem
            1 ino      inode number
            2 mode     file mode  (type    and permissions)
            3 nlink    number of (hard)    links to the file
            4 uid      numeric user ID of file's owner
            5 gid      numeric group ID    of file's owner
            6 rdev     the device identifier (special files only)
            7 size     total size of file, in bytes
            8 atime    last access time    since the epoch
            9 mtime    last modify time    since the epoch
           10 ctime    inode change time (NOT creation time!) since the    epoch
           11 blksize  preferred block size for    file system I/O
           12 blocks   actual number of    blocks allocated

          (The epoch was at 00:00 January 1, 1970 GMT.)

          If stat is passed the    special    filehandle consisting
          of an    underline, no stat is done, but    the current



     Page 78                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          contents of the stat structure from the last stat or
          filetest are returned.  Example:

              if (-x $file && (($d) = stat(_)) && $d < 0) {
              print    "$file is executable NFS file\n";
              }

          (This    works on machines only for which the device
          number is negative under NFS.)

          In scalar context, stat() returns a boolean value
          indicating success or    failure, and, if successful,
          sets the information associated with the special
          filehandle _.

      study    SCALAR

      study      Takes    extra time to study SCALAR ($_ if unspecified)
          in anticipation of doing many    pattern    matches    on the
          string before    it is next modified.  This may or may
          not save time, depending on the nature and number of
          patterns you are searching on, and on    the
          distribution of character frequencies    in the string
          to be    searched -- you    probably want to compare run
          times    with and without it to see which runs faster.
          Those    loops which scan for many short    constant
          strings (including the constant parts    of more
          complex patterns) will benefit most.    You may    have
          only one study() active at a time -- if you study a
          different scalar the first is    "unstudied".  (The way
          study() works    is this: a linked list of every
          character in the string to be    searched is made, so
          we know, for example,    where all the 'k' characters
          are.    From each search string, the rarest character
          is selected, based on    some static frequency tables
          constructed from some    C programs and English text.
          Only those places that contain this "rarest"
          character are    examined.)

          For example, here is a loop that inserts index
          producing entries before any line containing a
          certain pattern:

              while (<>) {
              study;
              print    ".IX foo\n" if /\bfoo\b/;
              print    ".IX bar\n" if /\bbar\b/;
              print    ".IX blurfl\n" if /\bblurfl\b/;
              # ...
              print;
              }




     Page 79                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          In searching for /\bfoo\b/, only those locations in
          $_ that contain "f" will be looked at, because "f"
          is rarer than    "o".  In general, this is a big    win
          except in pathological cases.     The only question is
          whether it saves you more time than it took to build
          the linked list in the first place.

          Note that if you have    to look    for strings that you
          don't    know till runtime, you can build an entire
          loop as a string and eval() that to avoid
          recompiling all your patterns    all the    time.
          Together with    undefining $/ to input entire files as
          one record, this can be very fast, often faster than
          specialized programs like _f_g_r_e_p(1).  The following
          scans    a list of files    (@files) for a list of words
          (@words), and    prints out the names of    those files
          that contain a match:

              $search =    'while (<>) { study;';
              foreach $word (@words) {
              $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
              }
              $search .= "}";
              @ARGV = @files;
              undef $/;
              eval $search;          # this screams
              $/ = "\n";      # put    back to    normal input delimiter
              foreach $file (sort keys(%seen)) {
              print    $file, "\n";
              }


      sub BLOCK

      sub NAME

      sub NAME BLOCK
          This is subroutine definition, not a real function
          _p_e_r _s_e.  With    just a NAME (and possibly prototypes),
          it's just a forward declaration.  Without a NAME,
          it's an anonymous function declaration, and does
          actually return a value: the CODE ref    of the closure
          you just created.  See the _p_e_r_l_s_u_b manpage and the
          _p_e_r_l_r_e_f manpage for details.

      substr EXPR,OFFSET,LEN,REPLACEMENT

      substr EXPR,OFFSET,LEN

      substr EXPR,OFFSET
          Extracts a substring out of EXPR and returns it.
          First    character is at    offset 0, or whatever you've



     Page 80                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          set $[ to (but don't do that).  If OFFSET is
          negative (or more precisely, less than $[), starts
          that far from    the end    of the string.    If LEN is
          omitted, returns everything to the end of the
          string.  If LEN is negative, leaves that many
          characters off the end of the    string.

          If you specify a substring that is partly outside
          the string, the part within the string is returned.
          If the substring is totally outside the string a
          warning is produced.

          You can use the substr() function as an lvalue, in
          which    case EXPR must be an lvalue.  If you assign
          something shorter than LEN, the string will shrink,
          and if you assign something longer than LEN, the
          string will grow to accommodate it.  To keep the
          string the same length you may need to pad or    chop
          your value using sprintf().

          An alternative to using substr() as an lvalue    is to
          specify the replacement string as the    4th argument.
          This allows you to replace parts of the EXPR and
          return what was there    before in one operation.

      symlink OLDFILE,NEWFILE
          Creates a new    filename symbolically linked to    the
          old filename.     Returns 1 for success,    0 otherwise.
          On systems that don't    support    symbolic links,
          produces a fatal error at run    time.  To check    for
          that,    use eval:

              $symlink_exists =     eval {    symlink("","");    1 };


      syscall LIST
          Calls    the system call    specified as the first element
          of the list, passing the remaining elements as
          arguments to the system call.     If unimplemented,
          produces a fatal error.  The arguments are
          interpreted as follows: if a given argument is
          numeric, the argument    is passed as an    int.  If not,
          the pointer to the string value is passed.  You are
          responsible to make sure a string is pre-extended
          long enough to receive any result that might be
          written into a string.  You can't use    a string
          literal (or other read-only string) as an argument
          to syscall() because Perl has    to assume that any
          string pointer might be written through.  If your
          integer arguments are    not literals and have never
          been interpreted in a    numeric    context, you may need
          to add 0 to them to force them to look like numbers.



     Page 81                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          This emulates    the syswrite() function    (or vice
          versa):

              require 'syscall.ph';          # may    need to    run h2ph
              $s = "hi there\n";
              syscall(&SYS_write, fileno(STDOUT), $s, length $s);

          Note that Perl supports passing of up    to only    14
          arguments to your system call, which in practice
          should usually suffice.

          Syscall returns whatever value returned by the
          system call it calls.     If the    system call fails,
          syscall() returns -1 and sets    $! (errno).  Note that
          some system calls can    legitimately return -1.     The
          proper way to    handle such calls is to    assign $!=0;
          before the call and check the    value of $! if syscall
          returns -1.

          There's a problem with syscall(&SYS_pipe): it
          returns the file number of the read end of the pipe
          it creates.  There is    no way to retrieve the file
          number of the    other end.  You    can avoid this problem
          by using pipe() instead.

      sysopen FILEHANDLE,FILENAME,MODE

      sysopen FILEHANDLE,FILENAME,MODE,PERMS
          Opens    the file whose filename    is given by FILENAME,
          and associates it with FILEHANDLE.  If FILEHANDLE is
          an expression, its value is used as the name of the
          real filehandle wanted.  This    function calls the
          underlying operating system's    open() function    with
          the parameters FILENAME, MODE, PERMS.

          The possible values and flag bits of the MODE
          parameter are    system-dependent; they are available
          via the standard module Fcntl.  For historical
          reasons, some    values work on almost every system
          supported by perl: zero means    read-only, one means
          write-only, and two means read/write.     We know that
          these    values do _n_o_t work under OS/390    Unix and on
          the Macintosh; you probably don't want to use    them
          in new code.

          If the file named by FILENAME    does not exist and the
          open() call creates it (typically because MODE
          includes the O_CREAT flag), then the value of    PERMS
          specifies the    permissions of the newly created file.
          If you omit the PERMS    argument to sysopen(), Perl
          uses the octal value 0666.  These permission values
          need to be in    octal, and are modified    by your



     Page 82                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          process's current umask.  The    umask value is a
          number representing disabled permissions bits--if
          your umask were 027 (group can't write; others can't
          read,    write, or execute), then passing sysopen()
          0666 would create a file with    mode 0640 (0666    &~ 027
          is 0640).

          If you find this umask() talk    confusing, here's some
          advice: supply a creation mode of 0666 for regular
          files    and one    of 0777    for directories    (in mkdir())
          and executable files.     This gives users the freedom
          of choice: if    they want protected files, they    might
          choose process umasks    of 022,    027, or    even the
          particularly antisocial mask of 077.    Programs
          should rarely    if ever    make policy decisions better
          left to the user.  The exception to this is when
          writing files    that should be kept private:  mail
          files, web browser cookies, ._r_h_o_s_t_s files, and so
          on.  In short, seldom    if ever    use 0644 as argument
          to sysopen() because that takes away the user's
          option to have a more    permissive umask.  Better to
          omit it.

          The IO::File module provides a more object-oriented
          approach, if you're into that    kind of    thing.

      sysread FILEHANDLE,SCALAR,LENGTH,OFFSET

      sysread FILEHANDLE,SCALAR,LENGTH
          Attempts to read LENGTH bytes    of data    into variable
          SCALAR from the specified FILEHANDLE,    using the
          system call _r_e_a_d(2).    It bypasses stdio, so mixing
          this with other kinds    of reads, print(), write(),
          seek(), or tell() can    cause confusion    because    stdio
          usually buffers data.     Returns the number of bytes
          actually read, 0 at end of file, or undef if there
          was an error.     SCALAR    will be    grown or shrunk    so
          that the last    byte actually read is the last byte of
          the scalar after the read.

          An OFFSET may    be specified to    place the read data at
          some place in    the string other than the beginning.
          A negative OFFSET specifies placement    at that    many
          bytes    counting backwards from    the end    of the string.
          A positive OFFSET greater than the length of SCALAR
          results in the string    being padded to    the required
          size with "\0" bytes before the result of the    read
          is appended.

      sysseek FILEHANDLE,POSITION,WHENCE
          Sets FILEHANDLE's system position using the system
          call _l_s_e_e_k(2).  It bypasses stdio, so    mixing this



     Page 83                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          with reads (other than sysread()), print(), write(),
          seek(), or tell() may    cause confusion.  FILEHANDLE
          may be an expression whose value gives the name of
          the filehandle.  The values for WHENCE are 0 to set
          the new position to POSITION,    1 to set the it    to the
          current position plus    POSITION, and 2    to set it to
          EOF plus POSITION (typically negative).  For WHENCE,
          you may use the constants SEEK_SET, SEEK_CUR,    and
          SEEK_END from    either the IO::Seekable    or the POSIX
          module.

          Returns the new position, or the undefined value on
          failure.  A position of zero is returned as the
          string "0 but    true"; thus sysseek() returns TRUE on
          success and FALSE on failure,    yet you    can still
          easily determine the new position.

      system LIST

      system PROGRAM LIST
          Does exactly the same    thing as "exec LIST" except
          that a fork is done first, and the parent process
          waits    for the    child process to complete.  Note that
          argument processing varies depending on the number
          of arguments.     If there is more than one argument in
          LIST,    or if LIST is an array with more than one
          value, starts    the program given by the first element
          of the list with arguments given by the rest of the
          list.     If there is only one scalar argument, the
          argument is checked for shell    metacharacters,    and if
          there    are any, the entire argument is    passed to the
          system's command shell for parsing (this is /bin/sh
          -c on    Unix platforms,    but varies on other
          platforms).  If there    are no shell metacharacters in
          the argument,    it is split into words and passed
          directly to execvp(),    which is more efficient.

          The return value is the exit status of the program
          as returned by the wait() call.  To get the actual
          exit value divide by 256.  See also the exec entry
          elsewhere in this document.  This is _N_O_T what    you
          want to use to capture the output from a command,
          for that you should use merely backticks or qx//, as
          described in the section on `_S_T_R_I_N_G` in the _p_e_r_l_o_p
          manpage.

          Like exec(), system()    allows you to lie to a program
          about    its name if you    use the    "system    PROGRAM    LIST"
          syntax.  Again, see the exec entry elsewhere in this
          document.

          Because system() and backticks block SIGINT and



     Page 84                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          SIGQUIT, killing the program they're running doesn't
          actually interrupt your program.

              @args = ("command", "arg1", "arg2");
              system(@args) == 0
               or die "system @args    failed:    $?"

          You can check    all the    failure    possibilities by
          inspecting $?    like this:

              $exit_value  = $?    >> 8;
              $signal_num  = $?    & 127;
              $dumped_core = $?    & 128;

          When the arguments get executed via the system
          shell, results and return codes will be subject to
          its quirks and capabilities.    See the    section    on
          `_S_T_R_I_N_G` in the _p_e_r_l_o_p manpage and the exec entry
          elsewhere in this documentfor    details.

      syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET

      syswrite FILEHANDLE,SCALAR,LENGTH
          Attempts to write LENGTH bytes of data from variable
          SCALAR to the    specified FILEHANDLE, using the    system
          call _w_r_i_t_e(2).  It bypasses stdio, so    mixing this
          with reads (other than sysread()), print(), write(),
          seek(), or tell() may    cause confusion    because    stdio
          usually buffers data.     Returns the number of bytes
          actually written, or undef if    there was an error.
          If the LENGTH    is greater than    the available data in
          the SCALAR after the OFFSET, only as much data as is
          available will be written.

          An OFFSET may    be specified to    write the data from
          some part of the string other    than the beginning.  A
          negative OFFSET specifies writing that many bytes
          counting backwards from the end of the string.  In
          the case the SCALAR is empty you can use OFFSET but
          only zero offset.

      tell FILEHANDLE

      tell      Returns the current position for FILEHANDLE.
          FILEHANDLE may be an expression whose    value gives
          the name of the actual filehandle.  If FILEHANDLE is
          omitted, assumes the file last read.

      telldir DIRHANDLE
          Returns the current position of the readdir()
          routines on DIRHANDLE.  Value    may be given to
          seekdir() to access a    particular location in a



     Page 85                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          directory.  Has the same caveats about possible
          directory compaction as the corresponding system
          library routine.

      tie VARIABLE,CLASSNAME,LIST
          This function    binds a    variable to a package class
          that will provide the    implementation for the
          variable.  VARIABLE is the name of the variable to
          be enchanted.     CLASSNAME is the name of a class
          implementing objects of correct type.     Any
          additional arguments are passed to the "new()"
          method of the    class (meaning TIESCALAR, TIEARRAY, or
          TIEHASH).  Typically these are arguments such    as
          might    be passed to the dbm_open() function of    C.
          The object returned by the "new()" method is also
          returned by the tie()    function, which    would be
          useful if you    want to    access other methods in
          CLASSNAME.

          Note that functions such as keys() and values() may
          return huge lists when used on large objects,    like
          DBM files.  You may prefer to    use the    each()
          function to iterate over such.  Example:

              #    print out history file offsets
              use NDBM_File;
              tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
              while (($key,$val) = each    %HIST) {
              print    $key, '    = ', unpack('L',$val), "\n";
              }
              untie(%HIST);

          A class implementing a hash should have the
          following methods:

              TIEHASH classname, LIST
              DESTROY this
              FETCH this, key
              STORE this, key, value
              DELETE this, key
              EXISTS this, key
              FIRSTKEY this
              NEXTKEY this, lastkey

          A class implementing an ordinary array should    have
          the following    methods:

              TIEARRAY classname, LIST
              DESTROY this
              FETCH this, key
              STORE this, key, value
              [others TBD]



     Page 86                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          A class implementing a scalar    should have the
          following methods:

              TIESCALAR    classname, LIST
              DESTROY this
              FETCH this,
              STORE this, value

          Unlike dbmopen(), the    tie() function will not    use or
          require a module for you--you    need to    do that
          explicitly yourself.    See the    _D_B__F_i_l_e    manpage    or the
          _C_o_n_f_i_g module    for interesting    tie() implementations.

          For further details see the _p_e_r_l_t_i_e manpage, the
          section on _t_i_e_d _V_A_R_I_A_B_L_E.

      tied VARIABLE
          Returns a reference to the object underlying
          VARIABLE (the    same value that    was originally
          returned by the tie()    call that bound    the variable
          to a package.)  Returns the undefined    value if
          VARIABLE isn't tied to a package.

      time      Returns the number of    non-leap seconds since
          whatever time    the system considers to    be the epoch
          (that's 00:00:00, January 1, 1904 for    MacOS, and
          00:00:00 UTC,    January    1, 1970    for most other
          systems).  Suitable for feeding to gmtime() and
          localtime().

      times      Returns a four-element list giving the user and
          system times,    in seconds, for    this process and the
          children of this process.

              ($user,$system,$cuser,$csystem) =    times;


      tr///      The transliteration operator.     Same as y///. See the
          _p_e_r_l_o_p manpage.

      truncate FILEHANDLE,LENGTH

      truncate EXPR,LENGTH
          Truncates the    file opened on FILEHANDLE, or named by
          EXPR,    to the specified length.  Produces a fatal
          error    if truncate isn't implemented on your system.
          Returns TRUE if successful, the undefined value
          otherwise.

      uc EXPR





     Page 87                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      uc      Returns an uppercased    version    of EXPR.  This is the
          internal function implementing the \U    escape in
          double-quoted    strings.  Respects current LC_CTYPE
          locale if use    locale in force.  See the _p_e_r_l_l_o_c_a_l_e
          manpage.

          If EXPR is omitted, uses $_.

      ucfirst EXPR

      ucfirst Returns the value of EXPR with the first character
          uppercased.  This is the internal function
          implementing the \u escape in    double-quoted strings.
          Respects current LC_CTYPE locale if use locale in
          force.  See the _p_e_r_l_l_o_c_a_l_e manpage.

          If EXPR is omitted, uses $_.

      umask    EXPR

      umask      Sets the umask for the process to EXPR and returns
          the previous value.  If EXPR is omitted, merely
          returns the current umask.

          If _u_m_a_s_k(2) is not implemented on your system    and
          you are trying to restrict access for    _y_o_u_r_s_e_l_f
          (i.e., (EXPR & 0700) > 0), produces a    fatal error at
          run time.  If    _u_m_a_s_k(2) is not    implemented and    you
          are not trying to restrict access for    yourself,
          returns undef.

          Remember that    a umask    is a number, usually given in
          octal; it is _n_o_t a string of octal digits.  See also
          the oct entry    elsewhere in this documentif all you
          have is a string.

      undef    EXPR

      undef      Undefines the    value of EXPR, which must be an
          lvalue.  Use only on a scalar    value, an array    (using
          "@"),    a hash (using "%"), a subroutine (using    "&"),
          or a typeglob    (using "<*>").    (Saying    undef
          $hash{$key} will probably not    do what    you expect on
          most predefined variables or DBM list    values,    so
          don't    do that; see the _d_e_l_e_t_e    manpage.)  Always
          returns the undefined    value.    You can    omit the EXPR,
          in which case    nothing    is undefined, but you still
          get an undefined value that you could, for instance,
          return from a    subroutine, assign to a    variable or
          pass as a parameter.    Examples:





     Page 88                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              undef $foo;
              undef $bar{'blurfl'};     # Compare to: delete $bar{'blurfl'};
              undef @ary;
              undef %hash;
              undef &mysub;
              undef *xyz;    # destroys $xyz, @xyz, %xyz, &xyz, etc.
              return (wantarray    ? (undef, $errmsg) : undef) if $they_blew_it;
              select undef, undef, undef, 0.25;
              ($a, $b, undef, $c) = &foo;    # Ignore third value returned

          Note that this is a unary operator, not a list
          operator.

      unlink LIST

      unlink  Deletes a list of files.  Returns the    number of
          files    successfully deleted.

              $cnt = unlink 'a', 'b', 'c';
              unlink @goners;
              unlink <*.bak>;

          Note:    unlink() will not delete directories unless
          you are superuser and    the ----UUUU flag is supplied    to
          Perl.     Even if these conditions are met, be warned
          that unlinking a directory can inflict damage    on
          your filesystem.  Use    rmdir()    instead.

          If LIST is omitted, uses $_.

      unpack TEMPLATE,EXPR
          Unpack() does    the reverse of pack(): it takes    a
          string representing a    structure and expands it out
          into a list value, returning the array value.     (In
          scalar context, it returns merely the    first value
          produced.)  The TEMPLATE has the same    format as in
          the pack() function.    Here's a subroutine that does
          substring:

              sub substr {
              my($what,$where,$howmuch) = @_;
              unpack("x$where a$howmuch", $what);
              }

          and then there's

              sub ordinal { unpack("c",$_[0]); } # same    as ord()

          In addition, you may prefix a    field with a %<number>
          to indicate that you want a <number>-bit checksum of
          the items instead of the items themselves.  Default
          is a 16-bit checksum.     For example, the following



     Page 89                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          computes the same number as the System V sum
          program:

              while (<>) {
              $checksum += unpack("%16C*", $_);
              }
              $checksum    %= 65536;

          The following    efficiently counts the number of set
          bits in a bit    vector:

              $setbits = unpack("%32b*", $selectmask);


      untie    VARIABLE
          Breaks the binding between a variable    and a package.
          (See tie().)

      unshift ARRAY,LIST
          Does the opposite of a shift().  Or the opposite of
          a push(), depending on how you look at it.  Prepends
          list to the front of the array, and returns the new
          number of elements in    the array.

              unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;

          Note the LIST    is prepended whole, not    one element at
          a time, so the prepended elements stay in the    same
          order.  Use reverse()    to do the reverse.

      use Module LIST

      use Module

      use Module VERSION LIST

      use VERSION
          Imports some semantics into the current package from
          the named module, generally by aliasing certain
          subroutine or    variable names into your package.  It
          is exactly equivalent    to

              BEGIN { require Module; import Module LIST; }

          except that Module _m_u_s_t be a bareword.

          If the first argument    to use is a number, it is
          treated as a version number instead of a module
          name.     If the    version    of the Perl interpreter    is
          less than VERSION, then an error message is printed
          and Perl exits immediately.  This is often useful if
          you need to check the    current    Perl version before



     Page 90                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          useing library modules that have changed in
          incompatible ways from older versions    of Perl.  (We
          try not to do    this more than we have to.)

          The BEGIN forces the require and import() to happen
          at compile time.  The    require    makes sure the module
          is loaded into memory    if it hasn't been yet.    The
          import() is not a builtin--it's just an ordinary
          static method    call into the "Module" package to tell
          the module to    import the list    of features back into
          the current package.    The module can implement its
          import() method any way it likes, though most
          modules just choose to derive    their import() method
          via inheritance from the Exporter class that is
          defined in the Exporter module.  See the _E_x_p_o_r_t_e_r
          manpage.  If no import() method can be found then
          the error is currently silently ignored.  This may
          change to a fatal error in a future version.

          If you don't want your namespace altered, explicitly
          supply an empty list:

              use Module ();

          That is exactly equivalent to

              BEGIN { require Module }

          If the VERSION argument is present between Module
          and LIST, then the use will call the VERSION method
          in class Module with the given version as an
          argument.  The default VERSION method, inherited
          from the Universal class, croaks if the given
          version is larger than the value of the variable
          $Module::VERSION.  (Note that    there is not a comma
          after    VERSION!)

          Because this is a wide-open interface, pragmas
          (compiler directives)    are also implemented this way.
          Currently implemented    pragmas    are:

              use integer;
              use diagnostics;
              use sigtrap qw(SEGV BUS);
              use strict  qw(subs vars refs);
              use subs      qw(afunc blurfl);

          Some of these    these pseudo-modules import semantics
          into the current block scope (like strict or
          integer, unlike ordinary modules, which import
          symbols into the current package (which are
          effective through the    end of the file).



     Page 91                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          There's a corresponding "no" command that unimports
          meanings imported by use, i.e., it calls unimport
          Module LIST instead of import().

              no integer;
              no strict    'refs';

          If no    unimport() method can be found the call    fails
          with a fatal error.

          See the _p_e_r_l_m_o_d manpage for a    list of    standard
          modules and pragmas.

      utime    LIST
          Changes the access and modification times on each
          file of a list of files.  The    first two elements of
          the list must    be the NUMERICAL access    and
          modification times, in that order.  Returns the
          number of files successfully changed.     The inode
          modification time of each file is set    to the current
          time.     This code has the same    effect as the "touch"
          command if the files already exist:

              #!/usr/bin/perl
              $now = time;
              utime $now, $now,    @ARGV;


      values HASH
          Returns a list consisting of all the values of the
          named    hash.  (In a scalar context, returns the
          number of values.)  The values are returned in an
          apparently random order, but it is the same order as
          either the keys() or each() function would produce
          on the same hash.  As    a side effect, it resets
          HASH's iterator.  See    also keys(), each(), and
          sort().

      vec EXPR,OFFSET,BITS
          Treats the string in EXPR as a vector    of unsigned
          integers, and    returns    the value of the bit field
          specified by OFFSET.    BITS specifies the number of
          bits that are    reserved for each entry    in the bit
          vector.  This    must be    a power    of two from 1 to 32.
          vec()    may also be assigned to, in which case
          parentheses are needed to give the expression    the
          correct precedence as    in

              vec($image, $max_x * $x +    $y, 8) = 3;

          Vectors created with vec() can also be manipulated
          with the logical operators |,    &, and ^, which    will



     Page 92                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          assume a bit vector operation    is desired when    both
          operands are strings.

          The following    code will build    up an ASCII string
          saying 'PerlPerlPerl'.  The comments show the    string
          after    each step. Note    that this code works in    the
          same way on big-endian or little-endian machines.

              my $foo =    '';
              vec($foo,     0, 32)    = 0x5065726C;      # 'Perl'
              vec($foo,     2, 16)    = 0x5065;      # 'PerlPe'
              vec($foo,     3, 16)    = 0x726C;      # 'PerlPerl'
              vec($foo,     8,  8)    = 0x50;          # 'PerlPerlP'
              vec($foo,     9,  8)    = 0x65;          # 'PerlPerlPe'
              vec($foo,    20,  4)    = 2;          # 'PerlPerlPe'   . "\x02"
              vec($foo,    21,  4)    = 7;          # 'PerlPerlPer'
                              # 'r'    is "\x72"
              vec($foo,    45,  2)    = 3;          # 'PerlPerlPer'  . "\x0c"
              vec($foo,    93,  1)    = 1;          # 'PerlPerlPer'  . "\x2c"
              vec($foo,    94,  1)    = 1;          # 'PerlPerlPerl'
                              # 'l'    is "\x6c"

          To transform a bit vector into a string or array of
          0's and 1's, use these:

              $bits = unpack("b*", $vector);
              @bits = split(//,    unpack("b*", $vector));

          If you know the exact    length in bits,    it can be used
          in place of the *.

      wait      Waits    for a child process to terminate and returns
          the pid of the deceased process, or -1 if there are
          no child processes.  The status is returned in $?.

      waitpid PID,FLAGS
          Waits    for a particular child process to terminate
          and returns the pid of the deceased process, or -1
          if there is no such child process.  The status is
          returned in $?.  If you say

              use POSIX    ":sys_wait_h";
              #...
              waitpid(-1,&WNOHANG);

          then you can do a non-blocking wait for any process.
          Non-blocking wait is available on machines
          supporting either the    _w_a_i_t_p_i_d(2) or _w_a_i_t_4(2) system
          calls.  However, waiting for a particular pid    with
          FLAGS    of 0 is    implemented everywhere.     (Perl
          emulates the system call by remembering the status
          values of processes that have    exited but have    not



     Page 93                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



          been harvested by the    Perl script yet.)

          See the _p_e_r_l_i_p_c manpage for other examples.

      wantarray
          Returns TRUE if the context of the currently
          executing subroutine is looking for a    list value.
          Returns FALSE    if the context is looking for a
          scalar.  Returns the undefined value if the context
          is looking for no value (void    context).

              return unless defined wantarray;      # don't bother doing more
              my @a = complex_calculation();
              return wantarray ? @a : "@a";


      warn LIST
          Produces a message on    STDERR just like die(),    but
          doesn't exit or throw    an exception.

          If LIST is empty and $@ already contains a value
          (typically from a previous eval) that    value is used
          after    appending "\t...caught"    to $@. This is useful
          for staying almost, but not entirely similar to
          die().

          If $@    is empty then the string "Warning: Something's
          wrong" is used.

          No message is    printed    if there is a $SIG{__WARN__}
          handler installed.  It is the    handler's
          responsibility to deal with the message as it    sees
          fit (like, for instance, converting it into a
          die()).  Most    handlers must therefore    make
          arrangements to actually display the warnings    that
          they are not prepared    to deal    with, by calling
          warn() again in the handler.    Note that this is
          quite    safe and will not produce an endless loop,
          since    __WARN__ hooks are not called from inside one.

          You will find    this behavior is slightly different
          from that of $SIG{__DIE__} handlers (which don't
          suppress the error text, but can instead call    die()
          again    to change it).

          Using    a __WARN__ handler provides a powerful way to
          silence all warnings (even the so-called mandatory
          ones).  An example:







     Page 94                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



              #    wipe out *all* compile-time warnings
              BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
              my $foo =    10;
              my $foo =    20;         # no warning about    duplicate my $foo,
                         # but hey,    you asked for it!
              #    no compile-time    or run-time warnings before here
              $DOWARN =    1;

              #    run-time warnings enabled after    here
              warn "\$foo is alive and $foo!";       # does show up

          See the _p_e_r_l_v_a_r manpage for details on setting %SIG
          entries, and for more    examples.

      write    FILEHANDLE

      write    EXPR

      write      Writes a formatted record (possibly multi-line) to
          the specified    FILEHANDLE, using the format
          associated with that file.  By default the format
          for a    file is    the one    having the same    name as    the
          filehandle, but the format for the current output
          channel (see the select() function) may be set
          explicitly by    assigning the name of the format to
          the $~ variable.

          Top of form processing is handled automatically:  if
          there    is insufficient    room on    the current page for
          the formatted    record,    the page is advanced by
          writing a form feed, a special top-of-page format is
          used to format the new page header, and then the
          record is written.  By default the top-of-page
          format is the    name of    the filehandle with "_TOP"
          appended, but    it may be dynamically set to the
          format of your choice    by assigning the name to the
          $^ variable while the    filehandle is selected.     The
          number of lines remaining on the current page    is in
          variable $-, which can be set    to 0 to    force a    new
          page.

          If FILEHANDLE    is unspecified,    output goes to the
          current default output channel, which    starts out as
          STDOUT but may be changed by the select() operator.
          If the FILEHANDLE is an EXPR,    then the expression is
          evaluated and    the resulting string is    used to    look
          up the name of the FILEHANDLE    at run time.  For more
          on formats, see the _p_e_r_l_f_o_r_m manpage.

          Note that write is _N_O_T the opposite of read().
          Unfortunately.




     Page 95                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))



      y///      The transliteration operator.     Same as tr///.     See
          the _p_e_r_l_o_p manpage.





















































     Page 96                        (printed 10/23/98)






     PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))      4444////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLFFFFUUUUNNNNCCCC((((1111))))























































     Page 97                        (printed 10/23/98)